shirokuma-docs 0.1.0-alpha.1

package/plugin/shirokuma-skills-en/skills/reviewing-on-issue/patterns/code-quality.md

@@ -0,0 +1,281 @@
+# Code Quality Patterns
+
+This document outlines code quality patterns and best practices for the Next.js TDD Blog CMS project.
+
+## Form Data Parsing Pattern
+
+Use the `parseFormData` utility for consistent parsing instead of manual parsing:
+
+```typescript
+// ✅ GOOD: Use parseFormData utility
+import { parseFormData } from "@/lib/utils/form"
+
+const data = parseFormData(formData, schema)
+
+// ❌ BAD: Manual parsing
+const data = Object.fromEntries(formData) as unknown as T
+```
+
+**Benefits:**
+- Type-safe parsing with Zod schema validation
+- Consistent error handling
+- Reduces boilerplate code
+- Centralized parsing logic
+
+## Transaction Error Handling
+
+Always wrap database transactions in try-catch blocks:
+
+```typescript
+// ✅ GOOD: Proper error handling
+try {
+  await db.transaction(async (tx) => {
+    // database operations
+    await tx.insert(table).values(data)
+  })
+} catch (error) {
+  return { success: false, error: "database_error" }
+}
+
+// ❌ BAD: No error handling
+await db.transaction(async (tx) => {
+  await tx.insert(table).values(data)
+})
+```
+
+**Benefits:**
+- Prevents unhandled rejections
+- Consistent error responses
+- Rollback protection
+- Better debugging
+
+## Type Consolidation
+
+Use the following criteria for organizing types:
+
+### Shared Package (`@repo/shared`)
+- Types used by 2 or more apps
+- Common domain models
+- Shared utility types
+
+```typescript
+// packages/shared/src/types/index.ts
+export interface User {
+  id: string
+  email: string
+  name: string
+}
+```
+
+### App-Specific Types
+- Types used within a single app
+- Located in `lib/actions/types.ts`
+
+```typescript
+// apps/admin/lib/actions/types.ts
+export interface CategoryFormState {
+  success: boolean
+  error?: string
+}
+```
+
+**Criteria:**
+- Used by 2+ apps → move to `@repo/shared` package
+- Used by 1 app → keep in app's `lib/actions/types.ts`
+
+## Date Handling
+
+Use consistent date formats for different contexts:
+
+### Database Storage
+```typescript
+// ✅ GOOD: Use Date object for DB inserts/updates
+{
+  createdAt: new Date(),
+  updatedAt: new Date()
+}
+```
+
+### API Responses
+```typescript
+// ✅ GOOD: Convert to ISO string for API responses
+{
+  createdAt: new Date().toISOString(),
+  updatedAt: new Date().toISOString()
+}
+```
+
+**Benefits:**
+- Consistent serialization
+- Timezone awareness
+- JSON compatibility
+- Database type compatibility
+
+## useActionState Pattern (React 19)
+
+Use the modern `useActionState` hook for form handling:
+
+```typescript
+// ✅ GOOD: Modern React 19 pattern
+import { useActionState } from "react"
+
+const [state, formAction, isPending] = useActionState(
+  serverAction,
+  initialState
+)
+
+<form action={formAction}>
+  {/* form fields */}
+  <button disabled={isPending}>Submit</button>
+</form>
+
+// ❌ BAD: Older useTransition pattern
+import { useTransition } from "react"
+
+const [isPending, startTransition] = useTransition()
+
+const handleSubmit = (formData: FormData) => {
+  startTransition(async () => {
+    await serverAction(formData)
+  })
+}
+```
+
+**Benefits:**
+- Built-in pending state
+- Automatic progressive enhancement
+- Better error handling
+- Type-safe action state
+- Simpler API
+
+---
+
+## Common Anti-Patterns
+
+### N+1 Queries
+
+```typescript
+// ❌ BAD: N+1 query pattern
+for (const category of categories) {
+  const posts = await getPostsByCategory(category.id)
+}
+
+// ✅ GOOD: Batch query
+const allPosts = await db.select().from(posts).where(inArray(posts.categoryId, categoryIds))
+```
+
+### Missing Error Handling
+
+```typescript
+// ❌ BAD: No error handling
+export async function create(formData: FormData) {
+  return await db.insert(features).values({...})
+}
+
+// ✅ GOOD: Proper error handling
+export async function create(formData: FormData): Promise<ActionResult> {
+  try {
+    const result = await db.insert(features).values({...})
+    return { success: true, data: result }
+  } catch (error) {
+    return { success: false, error: "Operation failed" }
+  }
+}
+```
+
+### Hardcoded Strings (i18n violation)
+
+```typescript
+// ❌ BAD: Hardcoded string
+<button>Save</button>
+
+// ✅ GOOD: Use translations
+const t = useTranslations("common")
+<button>{t("save")}</button>
+```
+
+### Sequential Queries (Should be Parallel)
+
+```typescript
+// ❌ BAD: Sequential queries
+const posts = await getPosts()
+const categories = await getCategories()
+const tags = await getTags()
+
+// ✅ GOOD: Parallel queries
+const [posts, categories, tags] = await Promise.all([
+  getPosts(),
+  getCategories(),
+  getTags(),
+])
+```
+
+### Missing setRequestLocale
+
+```typescript
+// ❌ BAD: Static rendering fails
+export default async function Page({ params }: Props) {
+  const { locale } = await params
+  const t = await getTranslations("namespace")
+  return <h1>{t("title")}</h1>
+}
+
+// ✅ GOOD: Works with static rendering
+export default async function Page({ params }: Props) {
+  const { locale } = await params
+  setRequestLocale(locale)  // REQUIRED
+  const t = await getTranslations("namespace")
+  return <h1>{t("title")}</h1>
+}
+```
+
+### Router Push After Login
+
+```typescript
+// ❌ BAD: Causes redirect loop
+const handleLogout = () => {
+  authClient.signOut()
+  router.push("/login")
+}
+
+// ✅ GOOD: Full page reload
+const handleLogout = () => {
+  authClient.signOut()
+  window.location.href = "/login"
+}
+```
+
+### ILIKE Without Escape
+
+```typescript
+// ❌ BAD: SQL injection vulnerable
+const pattern = `%${userInput}%`
+db.select().from(posts).where(ilike(posts.title, pattern))
+
+// ✅ GOOD: Escape special characters
+function escapeLikePattern(query: string): string {
+  return query.replace(/[%_\\]/g, "\\$&")
+}
+const pattern = `%${escapeLikePattern(userInput)}%`
+db.select().from(posts).where(ilike(posts.title, pattern))
+```
+
+---
+
+## Review Checklist
+
+When reviewing code, ensure:
+
+- [ ] Form data is parsed using `parseFormData` utility
+- [ ] Database transactions are wrapped in try-catch blocks
+- [ ] Types are in the appropriate location (shared vs app-specific)
+- [ ] Dates use correct format (Date for DB, ISO string for API)
+- [ ] Forms use `useActionState` instead of `useTransition`
+- [ ] Error handling is consistent across all server actions
+- [ ] Type safety is maintained throughout the code
+- [ ] No N+1 queries (use batch queries with `inArray()`)
+- [ ] No hardcoded UI strings (use i18n)
+- [ ] Independent queries are parallel (`Promise.all`)
+- [ ] `setRequestLocale()` is called in server components
+- [ ] Auth redirects use `window.location.href`
+- [ ] ILIKE patterns are properly escaped

package/plugin/shirokuma-skills-en/skills/reviewing-on-issue/patterns/docs-management.md

@@ -0,0 +1,123 @@
+# Documentation Management Patterns
+
+## Project Documentation Structure
+
+| Path | Purpose |
+|------|---------|
+| `docs/portal/index.html` | Main portal page |
+| `docs/portal/viewer.html` | Markdown viewer |
+| `docs/portal/*.html` | Guide pages |
+| `docs/generated/api-html/` | TypeDoc API docs |
+| `docs/generated/test-cases.md` | Test cases markdown |
+| `docs/generated/deps/` | Dependency graphs |
+| `docs/*.md` | Hand-written knowledge docs |
+| `docs/phase*/` | Phase implementation docs |
+
+## Document Types
+
+### Hand-Written Knowledge Documents
+
+Location: `docs/*.md` (root level)
+
+| Document Type | Purpose | Update Frequency |
+|---------------|---------|------------------|
+| Pattern docs | Development patterns, best practices | When patterns change |
+| Implementation records | Feature implementation history | One-time |
+| Guide docs | How-to guides | As needed |
+| Troubleshooting | Known issues and fixes | When issues discovered |
+
+### Auto-Generated Documents
+
+Location: `docs/generated/`
+
+| Document Type | Generation Command | Update Trigger |
+|---------------|-------------------|----------------|
+| API docs | `pnpm docs:api` | After Server Action changes |
+| Test cases | `pnpm docs:tests` | After test changes |
+| Dependency graphs | `pnpm docs:deps` | After dependency changes |
+| DB schema | `pnpm docs:dbml` | After schema changes |
+
+## Documentation Review Checklist
+
+When reviewing documentation:
+
+### Content Accuracy
+
+- [ ] Technical information matches current codebase
+- [ ] Code examples are runnable and correct
+- [ ] Version numbers are up-to-date
+- [ ] Command examples work with current setup
+
+### Status Tracking
+
+- [ ] Implementation status reflects actual state (✅, ⏳, ❌)
+- [ ] "Last Updated" date is current
+- [ ] "Next Steps" items are still relevant
+- [ ] Completed items are marked as such
+
+### Structure Quality
+
+- [ ] Has clear title and summary
+- [ ] Organized with appropriate sections
+- [ ] Code examples have syntax highlighting
+- [ ] Tables are properly formatted
+
+## Common Documentation Issues
+
+### Outdated Status
+
+```markdown
+## Implementation Status
+
+- ✅ Utility created: `packages/database/src/form-utils.ts`
+- ✅ Tests added: 19 test cases, 100% coverage
+- ✅ Exported from `@repo/database`
+- ⏳ Refactor Server Actions (recommended next step)  ← CHECK IF DONE
+
+## Next Steps  ← CHECK IF STILL RELEVANT
+
+1. Refactor `apps/admin/lib/actions/*.ts` files
+```
+
+**Fix**: Update status when implementation is complete.
+
+### Version Mismatch
+
+```markdown
+**Next.js Version**: 16.0.4  ← CHECK AGAINST package.json
+```
+
+**Fix**: Keep version numbers in sync with `package.json`.
+
+### Dead Links
+
+```markdown
+<!-- EXAMPLE: This is a dead link anti-pattern -->
+See [implementation details](./example-feature-doc.md)
+```
+
+**Fix**: Verify all internal links point to existing files.
+
+## Documentation Maintenance Commands
+
+```bash
+# Check if docs are outdated
+ls -la docs/*.md  # Compare dates with recent changes
+
+# Verify doc links
+grep -r "\[.*\](.*\.md)" docs/ | head -20
+
+# Check implementation status
+grep -r "⏳\|TODO\|WIP" docs/*.md
+
+# Find outdated version references
+grep -r "16\.0\.[0-9]" docs/  # Check Next.js versions
+```
+
+## Best Practices
+
+1. **Update Promptly**: Update docs immediately after implementation changes
+2. **Single Source of Truth**: Reference CLAUDE.md for authoritative versions
+3. **Status Tracking**: Use consistent status markers (✅, ⏳, ❌)
+4. **Date Stamps**: Include "Last Updated" in implementation docs
+5. **Link to Agent Knowledge**: Complex patterns should be in agent knowledge files

package/plugin/shirokuma-skills-en/skills/reviewing-on-issue/patterns/drizzle-orm.md

@@ -0,0 +1,314 @@
+# Drizzle ORM Patterns
+
+## Schema File Organization (Large Projects)
+
+Split schema files by domain for large projects:
+
+| File | Purpose |
+|------|---------|
+| `schema/index.ts` | Barrel exports + all relations |
+| `schema/common.ts` | Common column definitions |
+| `schema/auth.ts` | users, sessions, accounts, verifications |
+| `schema/content.ts` | posts, categories, tags, post_tags |
+| `schema/comments.ts` | comments |
+| `index.ts` | DB client + schema re-exports |
+| `constants.ts` | Common constants |
+
+### common.ts - Reusable Columns
+
+```typescript
+import { timestamp } from "drizzle-orm/pg-core"
+
+export const timestamps = {
+  createdAt: timestamp("created_at").notNull().defaultNow(),
+  updatedAt: timestamp("updated_at").notNull().defaultNow(),
+}
+```
+
+### auth.ts - Domain Tables
+
+```typescript
+import { pgTable, uuid, varchar, timestamp, text, boolean } from "drizzle-orm/pg-core"
+import { timestamps } from "./common"
+
+export const users = pgTable("user", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  email: varchar("email", { length: 255 }).notNull().unique(),
+  name: varchar("name", { length: 255 }),
+  role: varchar("role", { length: 20 }).notNull().default("user"),
+  emailVerified: timestamp("email_verified"),
+  ...timestamps,
+})
+
+export const sessions = pgTable("session", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  userId: uuid("user_id").notNull().references(() => users.id, { onDelete: "cascade" }),
+  token: varchar("token", { length: 255 }).notNull().unique(),
+  expiresAt: timestamp("expires_at").notNull(),
+  ...timestamps,
+})
+
+// accounts, verifications tables...
+```
+
+### schema/index.ts - Barrel + Relations
+
+```typescript
+// Re-export all tables
+export * from "./common"
+export * from "./auth"
+export * from "./content"
+export * from "./comments"
+
+// Define relations in one place to avoid circular imports
+import { relations } from "drizzle-orm"
+import { users, sessions, accounts } from "./auth"
+import { posts, categories, tags, postTags } from "./content"
+import { comments } from "./comments"
+
+export const usersRelations = relations(users, ({ many }) => ({
+  posts: many(posts),
+  comments: many(comments),
+  sessions: many(sessions),
+}))
+
+export const postsRelations = relations(posts, ({ one, many }) => ({
+  author: one(users, { fields: [posts.authorId], references: [users.id] }),
+  category: one(categories, { fields: [posts.categoryId], references: [categories.id] }),
+  comments: many(comments),
+  postTags: many(postTags),
+}))
+
+// ... other relations
+```
+
+### drizzle.config.ts
+
+```typescript
+export default defineConfig({
+  dialect: "postgresql",
+  schema: "./src/schema",  // Directory path including all files
+  out: "./drizzle",
+})
+```
+
+### Why Split Files
+
+- Clear domain boundaries (Auth / Content / Comments)
+- Reduced merge conflicts in team development
+- Easier to find and modify related tables
+- Scalability for growing projects (20+ tables)
+
+### Key Rules
+
+1. Define relations only in `schema/index.ts` (avoid circular imports)
+2. Export everything through barrel file
+3. Common patterns (timestamps, soft delete) go in `common.ts`
+4. Projects under 20 tables / 500 lines can use a single file
+
+## Queries with Relations
+
+```typescript
+const postsWithAuthor = await db
+  .select({
+    id: posts.id,
+    title: posts.title,
+    authorName: users.name,
+  })
+  .from(posts)
+  .leftJoin(users, eq(posts.authorId, users.id))
+  .where(eq(posts.status, "published"))
+```
+
+## Pagination
+
+```typescript
+const PAGE_SIZE = 20
+
+export async function getPaginated(page: number = 1) {
+  const offset = (page - 1) * PAGE_SIZE
+
+  const [items, countResult] = await Promise.all([
+    db.select().from(features).orderBy(desc(features.createdAt)).limit(PAGE_SIZE).offset(offset),
+    db.select({ count: count() }).from(features),
+  ])
+
+  return {
+    items,
+    pagination: {
+      page,
+      pageSize: PAGE_SIZE,
+      total: countResult[0]?.count ?? 0,
+      totalPages: Math.ceil((countResult[0]?.count ?? 0) / PAGE_SIZE),
+    },
+  }
+}
+```
+
+## ILIKE Search (Wildcard Escaping)
+
+```typescript
+function escapeLikePattern(query: string): string {
+  return query.replace(/[%_\\]/g, "\\$&")
+}
+
+const pattern = `%${escapeLikePattern(userInput)}%`
+db.select().from(posts).where(ilike(posts.title, pattern))
+```
+
+## Anti-Patterns
+
+### N+1 Queries
+
+```typescript
+// Bad: N+1 queries (one query per item)
+for (const category of categories) {
+  const posts = await getPostsByCategory(category.id)
+}
+
+// Good: Batch query with inArray()
+const allPosts = await db
+  .select()
+  .from(posts)
+  .where(inArray(posts.categoryId, categoryIds))
+
+const postsByCategory = allPosts.reduce((acc, post) => {
+  (acc[post.categoryId] ||= []).push(post)
+  return acc
+}, {})
+```
+
+### Mass Assignment
+
+```typescript
+// Bad: Direct spread allows unintended fields
+await db.update(posts).set({ ...formData })
+
+// Good: Explicit validated fields only
+const validated = Schema.parse(formData)
+await db.update(posts).set({
+  title: validated.title,
+  content: validated.content,
+})
+```
+
+## Migration Strategy
+
+- **Development**: `drizzle-kit push` for rapid iteration
+- **Production**: `drizzle-kit generate` + `migrate` for versioned migrations
+
+## Deprecated APIs
+
+- `InferModel` -> Use `InferSelectModel` and `InferInsertModel`
+
+## v1.0 (beta) Breaking Changes
+
+### Migration Folder Structure
+
+`journal.json` has been deprecated, and SQL files and snapshots are now grouped into individual folders. The `drizzle-kit drop` command has also been deprecated.
+
+```bash
+# Convert existing folder to new format
+npx drizzle-kit up
+```
+
+### Validator Package Consolidation
+
+| Old import | New import |
+|------------|-----------|
+| `drizzle-zod` | `drizzle-orm/zod` |
+| `drizzle-valibot` | `drizzle-orm/valibot` |
+| `drizzle-typebox` | `drizzle-orm/typebox` |
+| `drizzle-arktype` | `drizzle-orm/arktype` |
+
+### PostgreSQL Array
+
+`.array()` is no longer chainable. Use `.array('[][]')` for multidimensional arrays.
+
+### Relational Query Builder v2 (RQBv2)
+
+Migration from RQBv1 to RQBv2 is required. Provide all tables and relations during `drizzle()` initialization and use the `db.query` API.
+
+```typescript
+// v1: Define with relations()
+import { relations } from "drizzle-orm"
+
+// v2: Define with defineRelations() (recommended)
+// Details: orm.drizzle.team/docs/relations-v1-v2
+```
+
+## Type Safety
+
+```typescript
+// Define types from schema
+type Post = InferSelectModel<typeof posts>
+type NewPost = InferInsertModel<typeof posts>
+
+// Use in functions
+async function createPost(data: NewPost): Promise<Post> {
+  const [result] = await db.insert(posts).values(data).returning()
+  return result
+}
+```
+
+## Schema Documentation (shirokuma-docs)
+
+Describe columns and indexes using inline JSDoc comments. shirokuma-docs auto-extracts and generates documentation.
+
+### Column Comments
+
+Place JSDoc comments directly before column definitions:
+
+```typescript
+export const organizations = pgTable("organizations", {
+  /** Organization ID (UUID) */
+  id,
+  /** Organization name (display name) */
+  name: text("name").notNull(),
+  /** Organization slug (used in URL, unique constraint) */
+  slug: text("slug").notNull().unique(),
+  /** Organization description */
+  description: text("description"),
+  ...timestamps,
+})
+```
+
+### Index Comments
+
+Place JSDoc comments directly before index definitions:
+
+```typescript
+export const organizationMembers = pgTable(
+  "organization_members",
+  {
+    /** Membership ID */
+    id,
+    /** Organization ID */
+    organizationId: uuid("organization_id").notNull(),
+    /** User ID */
+    userId: text("user_id").notNull(),
+    ...timestamps,
+  },
+  (table) => [
+    /** Unique constraint on org-user combination (prevents duplicate memberships) */
+    uniqueIndex("org_members_org_user_idx").on(table.organizationId, table.userId),
+  ]
+)
+```
+
+### Do Not Use
+
+Do not use `@columns` or `@indexes` JSDoc tags (they duplicate inline comments):
+
+```typescript
+// NG - Do not use these tags
+/**
+ * @columns
+ *   - id: Organization ID
+ *   - name: Organization name
+ * @indexes
+ *   - org_slug_idx: Unique index for slug
+ */
+
+// OK - Use inline comments as shown above
+```