shirokuma-docs 0.1.0-alpha.1

package/plugin/shirokuma-skills-en/skills/reviewing-on-issue/docs/setup/infra-setup.md

@@ -0,0 +1,222 @@
+# Infrastructure Setup
+
+Guide for setting up shared infrastructure (nextjs-infra) with Traefik, PostgreSQL, Redis, and AWS-like services.
+
+## Architecture Overview
+
+**nextjs-infra (共有インフラ)**
+
+| Service | Description |
+|---------|-------------|
+| alb-traefik | リバースプロキシ (HTTPS終端) |
+| local-dns | `*.local.test` → 127.0.0.1 |
+| rds-postgres | PostgreSQL 16 |
+| elasticache-redis | Redis 7 |
+| ses-mailpit | メールテスト |
+| playwright | E2Eテスト用ブラウザサーバー |
+| localstack | AWS S3/SQS/SNS/DynamoDB等 |
+
+↕ `app-network` (external Docker network)
+
+**Application Projects** (e.g., nextjs-tdd-blog-cms)
+
+| Service | Domain |
+|---------|--------|
+| admin-app | admin.local.test |
+| public-app | public.local.test |
+| admin-test-app | admin-test.local.test (E2E用) |
+
+## Prerequisites
+
+- Docker & Docker Compose
+- mkcert (for HTTPS certificates)
+
+## 1. Generate SSL Certificates
+
+```bash
+# Install mkcert
+brew install mkcert  # macOS
+# or: sudo apt install mkcert  # Linux
+
+# Install local CA
+mkcert -install
+
+# Generate wildcard certificate for .local.test
+cd nextjs-infra/traefik/certs
+mkcert -cert-file local.pem -key-file local-key.pem "*.local.test" "localhost"
+```
+
+## 2. Create Docker Network
+
+```bash
+docker network create app-network
+```
+
+## 3. Start Infrastructure
+
+```bash
+cd nextjs-infra
+./scripts/start.sh
+```
+
+Or manually:
+
+```bash
+docker compose up -d
+```
+
+## 4. Application docker-compose.yml
+
+Applications connect to shared infra via external network and Traefik labels:
+
+```yaml
+services:
+  admin-app:
+    image: node:20-alpine
+    volumes:
+      - .:/app
+    working_dir: /app
+    command: npx pnpm --filter admin dev --port 3000
+    environment:
+      - NODE_ENV=development
+      # Connect to shared infra services
+      - DATABASE_URL=postgresql://postgres:postgres@rds-postgres:5432/blogcms_dev
+      - REDIS_URL=redis://elasticache-redis:6379
+      - EMAIL_SERVER_HOST=ses-mailpit
+      - EMAIL_SERVER_PORT=1025
+      - BETTER_AUTH_SECRET=${BETTER_AUTH_SECRET}
+      - BETTER_AUTH_URL=https://admin.local.test
+    networks:
+      - app-network
+    # Traefik auto-discovery via labels
+    labels:
+      - "traefik.enable=true"
+      - "traefik.http.routers.admin.rule=Host(`admin.local.test`)"
+      - "traefik.http.routers.admin.tls=true"
+      - "traefik.http.services.admin.loadbalancer.server.port=3000"
+
+networks:
+  app-network:
+    external: true
+    name: app-network
+```
+
+## 5. Traefik Label Configuration
+
+Traefik automatically routes traffic based on container labels:
+
+```yaml
+labels:
+  # Enable Traefik for this container
+  - "traefik.enable=true"
+  # Define routing rule (Host-based)
+  - "traefik.http.routers.{name}.rule=Host(`{hostname}.local.test`)"
+  # Enable TLS
+  - "traefik.http.routers.{name}.tls=true"
+  # Define backend port
+  - "traefik.http.services.{name}.loadbalancer.server.port={port}"
+```
+
+## 6. Service Endpoints
+
+### From Application Containers
+
+| Service | Hostname | Port |
+|---------|----------|------|
+| PostgreSQL | rds-postgres | 5432 |
+| Redis | elasticache-redis | 6379 |
+| Mailpit SMTP | ses-mailpit | 1025 |
+| LocalStack | localstack | 4566 |
+
+### From Host Machine
+
+| Service | URL | localhost Port |
+|---------|-----|----------------|
+| Admin App | https://admin.local.test | - |
+| PostgreSQL | - | 5432 |
+| Redis | - | 6379 |
+| Mailpit Web | https://mailpit.local.test | 8025 |
+| Traefik Dashboard | https://traefik.local.test | 8888 |
+| Adminer | https://adminer.local.test | - |
+| LocalStack | https://localstack.local.test | 4566 |
+| Playwright | - | 9323 |
+
+## 7. Database Setup
+
+```bash
+# Push schema to database
+DATABASE_URL="postgresql://postgres:postgres@localhost:5432/blogcms_dev" \
+  pnpm --filter @repo/database db:push
+
+# Seed data (from inside container)
+docker compose exec -T admin-app pnpm --filter @repo/database db:seed
+
+# Or from host
+DATABASE_URL="postgresql://postgres:postgres@localhost:5432/blogcms_dev" \
+  pnpm --filter @repo/database db:seed
+```
+
+## 8. E2E Test Environment
+
+Separate test apps with isolated database:
+
+```yaml
+admin-test-app:
+  image: node:20-alpine
+  command: sh -c "npx pnpm --filter admin build && npx pnpm --filter admin start --port 3000"
+  environment:
+    - NODE_ENV=production
+    - DATABASE_URL=postgresql://postgres:postgres@rds-postgres:5432/blogcms_test
+    - BETTER_AUTH_URL=https://admin-test.local.test
+  labels:
+    - "traefik.enable=true"
+    - "traefik.http.routers.admin-test.rule=Host(`admin-test.local.test`)"
+    - "traefik.http.routers.admin-test.tls=true"
+    - "traefik.http.services.admin-test.loadbalancer.server.port=3000"
+  profiles:
+    - development
+```
+
+Run E2E tests:
+
+```bash
+# Start test apps
+docker compose --profile development up -d admin-test-app public-test-app
+
+# Run Playwright tests (uses shared Playwright server)
+npx playwright test
+```
+
+## 9. Playwright Configuration
+
+Configure Playwright to use shared server:
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+  use: {
+    connectOptions: {
+      wsEndpoint: "ws://localhost:9323",
+    },
+    ignoreHTTPSErrors: true,
+  },
+})
+```
+
+## Troubleshooting
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| .test domain not resolving | DNS not configured | Run `./scripts/start.sh` in nextjs-infra |
+| SSL certificate error | mkcert CA not installed | Run `mkcert -install` |
+| Container can't connect to DB | Wrong hostname | Use `rds-postgres` not `localhost` |
+| E2E tests fail with connection refused | Playwright can't reach app | Check `extra_hosts` in Playwright container |
+| Network error between containers | Not on same network | Both must use `app-network` |
+
+## Adding New Applications
+
+1. Add services to your app's `docker-compose.yml`
+2. Use `app-network` (external)
+3. Add Traefik labels for routing
+4. Connect to infra services via container hostnames
+5. Add database to `nextjs-infra/rds/init/01-create-databases.sql` if needed

package/plugin/shirokuma-skills-en/skills/reviewing-on-issue/docs/setup/project-init.md

@@ -0,0 +1,176 @@
+# Project Initialization
+
+Guide for setting up a Next.js 16 monorepo project from scratch.
+
+## Prerequisites
+
+- Node.js 20.9.0+
+- pnpm 8.0.0+
+- Docker & Docker Compose
+
+## 1. Create Monorepo Structure
+
+```bash
+mkdir my-project && cd my-project
+pnpm init
+```
+
+### pnpm-workspace.yaml
+
+```yaml
+packages:
+  - 'apps/*'
+  - 'packages/*'
+```
+
+### Root package.json
+
+```json
+{
+  "name": "my-project",
+  "version": "0.1.0",
+  "private": true,
+  "engines": {
+    "node": ">=20.0.0",
+    "pnpm": ">=8.0.0"
+  },
+  "scripts": {
+    "dev:admin": "pnpm --filter admin dev",
+    "dev:public": "pnpm --filter public dev",
+    "build": "pnpm --filter admin build && pnpm --filter public build",
+    "lint": "pnpm --filter admin lint && pnpm --filter public lint"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.2"
+  }
+}
+```
+
+## 2. Create Next.js Apps
+
+```bash
+mkdir -p apps/admin apps/public packages/database
+cd apps/admin
+pnpm create next-app@latest . --typescript --tailwind --eslint --app --src-dir=false --import-alias="@/*"
+```
+
+### tsconfig.json (App)
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "paths": {
+      "@/*": ["./*"]
+    },
+    "plugins": [{ "name": "next" }]
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}
+```
+
+## 3. Create Database Package
+
+```bash
+cd packages/database
+pnpm init
+```
+
+### packages/database/package.json
+
+```json
+{
+  "name": "@repo/database",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "drizzle-orm": "^0.44.7",
+    "pg": "^8.16.3"
+  },
+  "devDependencies": {
+    "drizzle-kit": "^0.31.7",
+    "typescript": "^5.7.2"
+  },
+  "scripts": {
+    "db:push": "drizzle-kit push",
+    "db:studio": "drizzle-kit studio",
+    "db:seed": "tsx src/seed.ts"
+  }
+}
+```
+
+## 4. Link Packages
+
+In apps/admin/package.json:
+
+```json
+{
+  "dependencies": {
+    "@repo/database": "workspace:*"
+  }
+}
+```
+
+## 5. Install Dependencies
+
+```bash
+cd /path/to/project-root
+pnpm install
+```
+
+## Directory Structure
+
+| Path | Purpose |
+|------|---------|
+| `apps/admin/` | Admin CMS |
+| `apps/admin/app/[locale]/` | i18n routes |
+| `apps/admin/lib/actions/` | Server Actions |
+| `apps/admin/components/` | UI components |
+| `apps/admin/messages/` | i18n files |
+| `apps/public/` | Public site |
+| `packages/database/` | Shared Drizzle ORM |
+| `packages/database/src/schema/` | Table definitions |
+| `pnpm-workspace.yaml` | Monorepo config |
+| `docker-compose.yml` | Container setup |
+
+## Environment Variables
+
+Create `.env` in project root:
+
+```bash
+# Database
+DATABASE_URL=postgresql://postgres:password@localhost:5432/mydb
+
+# Auth
+BETTER_AUTH_SECRET=your-32-char-secret-here
+BETTER_AUTH_URL=https://admin.local.test
+
+# Redis (optional)
+REDIS_URL=redis://localhost:6379
+```
+
+## Next Steps
+
+1. [Database Setup](database-setup.md) - Drizzle ORM configuration
+2. [Auth Setup](auth-setup.md) - Better Auth integration
+3. [Styling Setup](styling-setup.md) - Tailwind v4 + shadcn/ui
+4. [Infra Setup](infra-setup.md) - Docker + Nginx

package/plugin/shirokuma-skills-en/skills/reviewing-on-issue/docs/setup/styling-setup.md

@@ -0,0 +1,324 @@
+# Styling Setup
+
+Guide for setting up Tailwind CSS v4 with shadcn/ui.
+
+## Prerequisites
+
+- Next.js 16 app created (see [project-init.md](project-init.md))
+
+## 1. Install Tailwind CSS v4
+
+```bash
+cd apps/admin
+pnpm add tailwindcss @tailwindcss/postcss
+```
+
+### postcss.config.mjs
+
+```javascript
+const config = {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+};
+export default config;
+```
+
+## 2. Configure globals.css (CSS-First)
+
+Tailwind v4 uses CSS-first configuration (no tailwind.config.ts).
+
+### app/globals.css
+
+```css
+@import "tailwindcss";
+
+@custom-variant dark (&:is(.dark *));
+
+@layer base {
+  :root {
+    --background: 0 0% 100%;
+    --foreground: 240 10% 3.9%;
+    --card: 0 0% 100%;
+    --card-foreground: 240 10% 3.9%;
+    --popover: 0 0% 100%;
+    --popover-foreground: 240 10% 3.9%;
+    --primary: 240 5.9% 10%;
+    --primary-foreground: 0 0% 98%;
+    --secondary: 240 4.8% 95.9%;
+    --secondary-foreground: 240 5.9% 10%;
+    --muted: 240 4.8% 95.9%;
+    --muted-foreground: 240 3.8% 45%;
+    --accent: 240 4.8% 95.9%;
+    --accent-foreground: 240 5.9% 10%;
+    --destructive: 0 72% 51%;
+    --destructive-foreground: 0 0% 98%;
+    --border: 240 5.9% 90%;
+    --input: 240 5.9% 90%;
+    --ring: 240 5.9% 10%;
+    --radius: 0.5rem;
+  }
+
+  .dark {
+    --background: 240 10% 3.9%;
+    --foreground: 0 0% 98%;
+    --card: 240 10% 3.9%;
+    --card-foreground: 0 0% 98%;
+    --popover: 240 10% 3.9%;
+    --popover-foreground: 0 0% 98%;
+    --primary: 0 0% 98%;
+    --primary-foreground: 240 5.9% 10%;
+    --secondary: 240 3.7% 15.9%;
+    --secondary-foreground: 0 0% 98%;
+    --muted: 240 3.7% 15.9%;
+    --muted-foreground: 240 5% 64.9%;
+    --accent: 240 3.7% 15.9%;
+    --accent-foreground: 0 0% 98%;
+    --destructive: 0 62.8% 30.6%;
+    --destructive-foreground: 0 0% 98%;
+    --border: 240 3.7% 15.9%;
+    --input: 240 3.7% 15.9%;
+    --ring: 240 4.9% 83.9%;
+  }
+}
+
+@theme inline {
+  /* Sidebar dimensions - @theme inline avoids @property registration issues in production */
+  --sidebar-width: 16rem;
+  --sidebar-width-icon: 3rem;
+  --font-sans: var(--font-inter), ui-sans-serif, system-ui, sans-serif;
+  --color-background: hsl(var(--background));
+  --color-foreground: hsl(var(--foreground));
+  --color-card: hsl(var(--card));
+  --color-card-foreground: hsl(var(--card-foreground));
+  --color-popover: hsl(var(--popover));
+  --color-popover-foreground: hsl(var(--popover-foreground));
+  --color-primary: hsl(var(--primary));
+  --color-primary-foreground: hsl(var(--primary-foreground));
+  --color-secondary: hsl(var(--secondary));
+  --color-secondary-foreground: hsl(var(--secondary-foreground));
+  --color-muted: hsl(var(--muted));
+  --color-muted-foreground: hsl(var(--muted-foreground));
+  --color-accent: hsl(var(--accent));
+  --color-accent-foreground: hsl(var(--accent-foreground));
+  --color-destructive: hsl(var(--destructive));
+  --color-destructive-foreground: hsl(var(--destructive-foreground));
+  --color-border: hsl(var(--border));
+  --color-input: hsl(var(--input));
+  --color-ring: hsl(var(--ring));
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+}
+
+@layer base {
+  * {
+    border-color: hsl(var(--border));
+  }
+  body {
+    background-color: hsl(var(--background));
+    color: hsl(var(--foreground));
+  }
+}
+```
+
+## 3. Initialize shadcn/ui
+
+**IMPORTANT**: Use `@canary` for Tailwind v4 compatibility.
+
+```bash
+cd apps/admin
+npx shadcn@canary init
+```
+
+Answer the prompts:
+- Style: new-york
+- Base color: neutral
+- CSS variables: yes
+
+### components.json (Generated)
+
+```json
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": true,
+  "tsx": true,
+  "tailwind": {
+    "css": "app/globals.css",
+    "baseColor": "neutral",
+    "cssVariables": true
+  },
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  }
+}
+```
+
+## 4. Add Components
+
+```bash
+# Add individual components
+npx shadcn@canary add button card input label -y
+
+# After adding, run the CSS variable fix script
+./scripts/fix-tailwind-v4-css-vars.sh --yes apps/admin/components/ui
+```
+
+## 5. CSS Variable Fix Script
+
+shadcn CLI generates v3 syntax (`[--var]`) which doesn't work in v4. This script converts to `[var(--var)]`.
+
+### scripts/fix-tailwind-v4-css-vars.sh
+
+```bash
+#!/bin/bash
+
+# Usage: ./scripts/fix-tailwind-v4-css-vars.sh [--yes] <directory>
+
+AUTO_YES=false
+if [ "$1" = "--yes" ]; then
+  AUTO_YES=true
+  shift
+fi
+
+TARGET_DIR="${1:-apps/admin/components/ui}"
+
+if [ ! -d "$TARGET_DIR" ]; then
+  echo "Directory not found: $TARGET_DIR"
+  exit 1
+fi
+
+echo "Fixing CSS variables in: $TARGET_DIR"
+
+# Find files with v3 syntax
+FILES=$(grep -rl '\[--' "$TARGET_DIR" --include="*.tsx" --include="*.ts" 2>/dev/null)
+
+if [ -z "$FILES" ]; then
+  echo "No files need fixing."
+  exit 0
+fi
+
+echo "Files to fix:"
+echo "$FILES"
+
+if [ "$AUTO_YES" = false ]; then
+  read -p "Proceed? (y/n) " -n 1 -r
+  echo
+  if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+    exit 1
+  fi
+fi
+
+# Replace [--var] with [var(--var)]
+for file in $FILES; do
+  sed -i 's/\[--\([a-zA-Z0-9_-]*\)\]/[var(--\1)]/g' "$file"
+  echo "Fixed: $file"
+done
+
+echo "Done!"
+```
+
+Make executable:
+
+```bash
+chmod +x scripts/fix-tailwind-v4-css-vars.sh
+```
+
+## 6. Utility Function
+
+### lib/utils.ts
+
+```typescript
+import { type ClassValue, clsx } from "clsx"
+import { twMerge } from "tailwind-merge"
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}
+```
+
+Install dependencies:
+
+```bash
+pnpm add clsx tailwind-merge class-variance-authority
+```
+
+## 7. Dark Mode Setup
+
+### components/theme-provider.tsx
+
+```typescript
+"use client"
+
+import * as React from "react"
+import { ThemeProvider as NextThemesProvider } from "next-themes"
+
+export function ThemeProvider({ children, ...props }: React.ComponentProps<typeof NextThemesProvider>) {
+  return <NextThemesProvider {...props}>{children}</NextThemesProvider>
+}
+```
+
+### app/layout.tsx
+
+```typescript
+import { ThemeProvider } from "@/components/theme-provider"
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="ja" suppressHydrationWarning>
+      <body>
+        <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
+          {children}
+        </ThemeProvider>
+      </body>
+    </html>
+  )
+}
+```
+
+## CSS Variable Syntax (CRITICAL)
+
+| v3 Syntax (Wrong) | v4 Syntax (Correct) |
+|-------------------|---------------------|
+| `w-[--sidebar-width]` | `w-[var(--sidebar-width)]` |
+| `bg-[--custom-color]` | `bg-[var(--custom-color)]` |
+| `h-10!` (important) | `h-10!` (same, suffix) |
+
+## Browser Requirements
+
+Tailwind v4 uses modern CSS features:
+- Safari 16.4+ (`@property`, `color-mix()`)
+- Chrome 111+
+- Edge 111+
+- Firefox 128+
+
+## Common Issues
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| Styles not applied | v3 syntax | Run fix script |
+| Sidebar overlap | CSS variables wrong | Run fix script |
+| Dark mode flicker | Missing suppressHydrationWarning | Add to html tag |
+| **本番のみCSS変数が効かない** | @property 登録 | `@theme inline` で定義 |
+
+### @theme inline について
+
+Tailwind v4 は本番ビルドで `@property` を使ってCSS変数を登録します。これにより、インラインスタイルからの継承が無効化される場合があります。
+
+コンポーネント（例: shadcn/ui sidebar）がインラインスタイルでCSS変数を設定する場合、その変数を `@theme inline` で定義することで問題を回避できます。
+
+```css
+@theme inline {
+  --sidebar-width: 16rem;  /* @property 登録を回避 */
+}
+```
+
+## Next Steps
+
+- [Infra Setup](infra-setup.md) - Docker and Nginx configuration