create-fullstack-scaffold 0.1.0

package/template/PROJECT_SUMMARY.md

@@ -0,0 +1,325 @@
+# Project Template Summary
+
+## Created Project Structure
+
+A complete React + Hono full-stack application template following the project-framework architecture.
+
+## Directory Structure
+
+```
+template/
+├── src/
+│   ├── client/                     # React Frontend
+│   │   ├── App.tsx                # Main Todo List component
+│   │   ├── main.tsx               # React entry point
+│   │   ├── index.css              # Global styles
+│   │   ├── components/
+│   │   │   └── __tests__/         # Component tests
+│   │   ├── stores/
+│   │   │   ├── todoStore.ts       # Zustand state management
+│   │   │   ├── notificationStore.ts # SSE notifications store
+│   │   │   └── __tests__/
+│   │   ├── services/
+│   │   │   └── apiClient.ts       # Hono RPC client
+│   │   ├── hooks/
+│   │   │   └── useWS.ts          # WebSocket hook
+│   │   └── pages/
+│   │       └── NotificationPage.tsx
+│   │
+│   ├── server/                     # Hono Backend
+│   │   ├── app.ts                 # Server entry with middleware
+│   │   ├── module-todos/          # Todo feature module
+│   │   │   ├── routes/
+│   │   │   │   └── todos-routes.ts  # API endpoints (Hono RPC)
+│   │   │   ├── services/
+│   │   │   │   └── todo-service.ts  # Business logic
+│   │   │   └── __tests__/
+│   │   ├── module-chat/           # WebSocket chat module
+│   │   │   ├── routes/
+│   │   │   │   └── chat-routes.ts
+│   │   │   ├── services/
+│   │   │   │   └── chat-service.ts
+│   │   │   └── __tests__/
+│   │   ├── module-notifications/  # SSE notifications module
+│   │   │   ├── routes/
+│   │   │   │   └── notification-routes.ts
+│   │   │   ├── services/
+│   │   │   │   └── notification-service.ts
+│   │   │   └── __tests__/
+│   │   ├── core/                  # Core runtime
+│   │   │   ├── runtime.ts         # Runtime adapter interface
+│   │   │   ├── runtime-node.ts   # Node.js runtime
+│   │   │   ├── runtime-cloudflare.ts # Cloudflare runtime
+│   │   │   ├── realtime-core.ts   # Real-time core
+│   │   │   ├── typed-runtime.ts  # Type-safe runtime
+│   │   │   └── realtime-scanner.ts # Auto-register realtime
+│   │   ├── middleware/             # Express middleware
+│   │   │   ├── cors.ts
+│   │   │   ├── logger.ts
+│   │   │   ├── error-handler.ts
+│   │   │   └── realtime-env.ts    # Realtime env middleware
+│   │   ├── test-utils/
+│   │   │   ├── test-client.ts     # Test client factory
+│   │   │   └── test-server.ts     # Test server (WebSocket)
+│   │   ├── entries/
+│   │   │   ├── node.ts           # Node.js entry point
+│   │   │   └── cloudflare.ts     # Cloudflare entry point
+│   │   └── integration/
+│   │       └── todos-api.test.ts  # Integration tests
+│   │
+│   └── shared/                     # Shared Types
+│       ├── core/                   # Framework Layer
+│       │   ├── ws-client.ts       # WebSocket client
+│       │   ├── sse-client.ts      # SSE client
+│       │   ├── api-schemas.ts    # API response schemas
+│       │   ├── protocol-types.ts  # Protocol type utilities
+│       │   └── index.ts          # Framework exports
+│       ├── modules/               # Business Layer
+│       │   ├── chat/
+│       │   │   └── index.ts      # Chat protocol schema
+│       │   ├── todos/
+│       │   │   ├── schemas.ts    # Todo schemas
+│       │   │   └── index.ts
+│       │   └── notifications/
+│       │       ├── schemas.ts    # Notification + SSE schemas
+│       │       └── index.ts
+│       └── schemas/               # Unified exports
+│           └── index.ts
+│
+├── lint-scripts/
+│   ├── config/
+│   │   └── project.config.ts      # Validation config
+│   ├── validators/
+│   │   ├── client-rpc.validator.ts
+│   │   ├── server-rpc.validator.ts
+│   │   ├── imports.validator.ts
+│   │   └── index.ts
+│   └── validate-all.ts            # Pre-commit validation
+│
+├── eslint-rules/
+│   ├── layer-boundary.js          # Framework/Business layer separation
+│   ├── no-direct-ws-sse.js        # WebSocket/SSE protection
+│   ├── protect-ws-sse-interface.js
+│   ├── require-type-safe-test-client.js
+│   ├── require-hono-chain-syntax.js
+│   ├── no-ambiguous-file-paths.js
+│   └── no-util-functions-in-service.js
+│
+├── .claude/
+│   └── rules/
+│       ├── project-rules.md
+│       ├── client-component-rules.md
+│       ├── client-service-rules.md
+│       ├── zustand-rules.md
+│       ├── websocket-rules.md
+│       ├── sse-rules.md
+│       ├── shared-types-rules.md
+│       ├── layer-boundary-rules.md
+│       ├── testing-standards.md
+│       └── hono-testing-best-practices.md
+│
+└── Documentation
+    ├── README.md                  # User-facing documentation
+    ├── QUICKSTART.md              # Quick start guide
+    ├── DESIGN.md                  # Architecture documentation
+    └── CLAUDE.md                  # Claude Code guidelines
+```
+
+## Framework Layer vs Business Layer
+
+The project has clear separation between framework and business layers:
+
+### Framework Layer (`src/shared/core/`)
+
+- Generic, reusable infrastructure code
+- Examples: `ws-client.ts`, `sse-client.ts`, `api-schemas.ts`
+- Should not be modified by business code directly
+
+### Business Layer (`src/shared/modules/`)
+
+- Business-specific schemas and protocols
+- Examples: `chat/`, `todos/`, `notifications/`
+- Organized by feature modules
+
+## Key Features Implemented
+
+### 1. Architecture
+
+- ✅ Monorepo-style structure with client/server separation
+- ✅ Shared types for end-to-end type safety
+- ✅ Single-port development (3010) using @hono/vite-dev-server
+- ✅ Modular backend with feature-based organization
+- ✅ Framework layer vs Business layer separation
+
+### 2. Frontend (React + Vite)
+
+- ✅ React 18 with TypeScript
+- ✅ Zustand state management
+- ✅ Hono RPC for type-safe API calls
+- ✅ Todo List UI with CRUD operations
+- ✅ Error handling and loading states
+
+### 3. Backend (Hono)
+
+- ✅ Hono with OpenAPI/Swagger support
+- ✅ Zod validation for all endpoints
+- ✅ CORS and error handling middleware
+- ✅ Module-based route organization
+- ✅ Health check endpoint
+- ✅ Middleware for realtime env
+
+### 4. Real-time Features
+
+- ✅ WebSocket support with `$ws()` method
+- ✅ SSE support with `$sse()` method
+- ✅ Type-safe real-time communication
+- ✅ Runtime abstraction (Node.js / Cloudflare Workers)
+- ✅ Auto-register realtime via scanner
+
+### 5. Testing
+
+- ✅ Vitest configuration for unit tests
+- ✅ Integration tests for API endpoints
+- ✅ WebSocket tests (requires server)
+- ✅ SSE tests (no server needed)
+- ✅ jsdom environment for client tests
+- ✅ Node environment for server tests
+
+### 6. Code Quality
+
+- ✅ ESLint with TypeScript support
+- ✅ Custom ESLint rules for WebSocket/SSE
+- ✅ Layer boundary rules for framework/business separation
+- ✅ Prettier for code formatting
+- ✅ Pre-commit hooks with Husky
+- ✅ Validation script for common issues
+- ✅ lint-staged for efficient formatting
+
+## API Endpoints
+
+### Todos
+
+- `GET /api/todos` - List all todos
+- `GET /api/todos/:id` - Get todo by ID
+- `POST /api/todos` - Create new todo
+- `PUT /api/todos/:id` - Update todo
+- `DELETE /api/todos/:id` - Delete todo
+
+### WebSocket
+
+- `GET /api/chat/ws` - WebSocket chat endpoint
+  - RPC methods: `echo`, `ping`
+  - Events: `notification`
+
+### SSE
+
+- `GET /api/notifications/stream` - SSE notifications endpoint
+  - Events: `notification`, `ping`, `connected`
+
+### Health
+
+- `GET /health` - Health check
+- `GET /` - Root endpoint with HTML
+- `GET /docs` - OpenAPI documentation
+
+## Data Models
+
+### Todo
+
+```typescript
+interface Todo {
+  id: number
+  title: string
+  description?: string
+  status: 'pending' | 'in_progress' | 'completed'
+  createdAt: string
+  updatedAt: string
+}
+```
+
+### Notification
+
+```typescript
+interface AppNotification {
+  id: string
+  type: 'info' | 'warning' | 'success' | 'error'
+  title: string
+  message: string
+  read: boolean
+  createdAt: string
+}
+```
+
+## Usage
+
+### Installation
+
+```bash
+npm install
+```
+
+### Development
+
+```bash
+npm run dev  # Starts on http://localhost:3010
+```
+
+### Testing
+
+```bash
+npm test              # Run all tests
+npm run test:unit     # Unit tests only
+npm run test:integration  # Integration tests only
+```
+
+### Build
+
+```bash
+npm run build
+npm run preview
+```
+
+## Technical Highlights
+
+### 1. Type Safety
+
+- End-to-end type safety from database to UI
+- Hono RPC provides compile-time validation
+- Zod schemas for runtime validation
+- Type-safe WebSocket and SSE
+
+### 2. Real-time Features
+
+- WebSocket: Bidirectional communication with RPC
+- SSE: Unidirectional server-to-client streaming
+- Type-safe protocols with Zod schemas
+
+### 3. Framework/Business Layer Separation
+
+- Clear boundaries enforced by ESLint
+- Framework layer: reusable infrastructure
+- Business layer: feature-specific code
+
+### 4. Scalability
+
+- Modular architecture easy to extend
+- Feature-based organization
+- Clear separation of concerns
+
+### 5. Developer Experience
+
+- Clear project structure
+- Comprehensive documentation
+- Automated code quality checks
+- Easy onboarding for new developers
+
+## Next Steps
+
+To use this template for a new project:
+
+1. Copy the template directory
+2. Customize package.json (name, description)
+3. Update environment variables
+4. Modify the Todo module or create new modules
+5. Add your own features following the established patterns
+6. Update documentation as needed

package/template/QUICKSTART.md

@@ -0,0 +1,305 @@
+# Quick Start Guide
+
+## Prerequisites
+
+- Node.js 18+
+- npm or yarn
+
+## Installation
+
+```bash
+# Install dependencies
+npm install
+```
+
+## Development
+
+```bash
+# Start development server (port 3010)
+npm run dev
+
+# The app will be available at http://localhost:3010
+```
+
+## Project Structure
+
+```
+template/
+├── src/
+│   ├── client/              # React frontend
+│   │   ├── App.tsx         # Main component
+│   │   ├── stores/         # Zustand state management
+│   │   ├── services/       # API clients (apiClient)
+│   │   ├── hooks/         # Custom hooks
+│   │   ├── pages/         # Page components
+│   │   └── components/    # UI components
+│   ├── server/             # Hono backend
+│   │   ├── module-todos/  # Todo feature module
+│   │   ├── module-chat/   # WebSocket chat module
+│   │   ├── module-notifications/ # SSE notifications module
+│   │   ├── core/          # Core services (runtime, realtime)
+│   │   ├── middleware/    # Express middleware
+│   │   ├── test-utils/   # Test utilities
+│   │   └── entries/       # Entry points (node.ts, cloudflare.ts)
+│   └── shared/            # Shared types
+│       ├── core/          # Framework layer (ws-client, sse-client)
+│       ├── modules/       # Business layer (chat, todos, notifications)
+│       └── schemas/       # Unified exports
+├── lint-scripts/           # Validation scripts
+├── .husky/                # Git hooks
+└── [config files]
+```
+
+## Key Files to Understand
+
+1. **src/shared/modules/** - Business schemas (chat, todos, notifications)
+2. **src/server/app.ts** - Hono server with RPC
+3. **src/server/module-todos/routes/todos-routes.ts** - API endpoints
+4. **src/client/App.tsx** - React UI component
+5. **src/client/stores/todoStore.ts** - Zustand state management
+6. **src/client/services/apiClient.ts** - Type-safe API client
+
+## Testing
+
+```bash
+# Run all tests
+npm test
+
+# Run unit tests only
+npm run test:unit
+
+# Run integration tests only
+npm run test:integration
+
+# Run tests with coverage
+npm test -- --coverage
+```
+
+### Testing Real-time Features
+
+| Feature   | Requires Server | Test Method                 |
+| --------- | --------------- | --------------------------- |
+| HTTP API  | ❌ No           | `createTestClient()`        |
+| SSE       | ❌ No           | `$sse()` with `app.fetch()` |
+| WebSocket | ✅ Yes          | `createTestServer()`        |
+
+## Adding a New Feature
+
+### 1. Create Server Module
+
+```bash
+mkdir -p src/server/module-{feature}/routes
+mkdir -p src/server/module-{feature}/services
+mkdir -p src/server/module-{feature}/__tests__
+```
+
+### 2. Define Types
+
+Add to `src/shared/modules/{feature}/schemas.ts`:
+
+```typescript
+import { z } from '@hono/zod-openapi'
+
+export const NewFeatureSchema = z.object({
+  id: z.string().uuid(),
+  name: z.string().min(1),
+})
+
+export type NewFeature = z.infer<typeof NewFeatureSchema>
+```
+
+### 3. Create Service
+
+`src/server/module-{feature}/services/feature-service.ts`:
+
+```typescript
+export async function listFeatures() {
+  // Business logic
+}
+```
+
+### 4. Create Routes
+
+`src/server/module-{feature}/routes/feature-routes.ts`:
+
+```typescript
+import { createRoute } from '@hono/zod-openapi'
+import { OpenAPIHono } from '@hono/zod-openapi'
+
+const app = new OpenAPIHono()
+
+const listRoute = createRoute({
+  method: 'get',
+  path: '/features',
+  // ... route definition
+})
+
+app.openapi(listRoute, async c => {
+  const features = await featureService.listFeatures()
+  return c.json({ success: true, data: features })
+})
+
+export const featureRoutes = app
+```
+
+### 5. Register Routes
+
+Add to `src/server/app.ts`:
+
+```typescript
+import { featureRoutes } from './module-features/routes/feature-routes'
+
+app.route('/api', featureRoutes)
+```
+
+### 6. Create Client Store
+
+`src/client/stores/todoStore.ts`:
+
+```typescript
+import { create } from 'zustand'
+import { apiClient } from '@client/services/apiClient'
+
+export const useTodoStore = create(set => ({
+  todos: [],
+  fetchTodos: async () => {
+    const response = await apiClient.api.todos.$get()
+    const result = await response.json()
+    set({ todos: result.data })
+  },
+}))
+```
+
+### 7. Create UI Component
+
+```typescript
+import { useTodoStore } from '@client/stores/todoStore';
+
+export function TodoList() {
+  const todos = useTodoStore((state) => state.todos);
+
+  return (
+    <div>
+      {todos.map((todo) => (
+        <div key={todo.id}>{todo.title}</div>
+      ))}
+    </div>
+  );
+}
+```
+
+## Real-time Features
+
+### WebSocket
+
+```typescript
+// Server: Define protocol in src/shared/modules/chat/
+import { ChatProtocolSchema } from '@shared/modules/chat'
+
+// Client: Use $ws()
+const ws = apiClient.api.chat.ws.$ws()
+const result = await ws.call('echo', { message: 'hello' })
+ws.on('notification', n => console.log(n))
+```
+
+### SSE
+
+```typescript
+// Server: Define protocol in src/shared/modules/notifications/
+import { AppSSEProtocolSchema } from '@shared/schemas'
+
+// Client: Use $sse()
+const conn = await apiClient.api.notifications.stream.$sse()
+conn.on('notification', n => console.log(n))
+conn.on('ping', p => console.log(p.timestamp))
+```
+
+### SSE Broadcast Pattern
+
+When creating notifications, use the broadcast function in service layer:
+
+```typescript
+// In service layer - use createNotificationAndBroadcast
+import { createNotificationAndBroadcast } from '@server/module-notifications/services/notification-service'
+
+// The service automatically handles broadcasting
+const notification = await createNotificationAndBroadcast(input)
+```
+
+## Framework Layer vs Business Layer
+
+The project has clear separation between framework and business layers:
+
+**Framework Layer** (`src/shared/core/`):
+
+- Generic, reusable infrastructure code
+- Examples: `ws-client.ts`, `sse-client.ts`, `api-schemas.ts`
+- Should not be modified by business code directly
+
+**Business Layer** (`src/shared/modules/`):
+
+- Business-specific schemas and protocols
+- Examples: `chat/`, `todos/`, `notifications/`
+
+## Code Quality
+
+```bash
+# Format code
+npm run format
+
+# Lint code
+npm run lint
+
+# Type check
+npm run typecheck
+
+# Run validation script
+node --import tsx/esm lint-scripts/validate-all.ts
+```
+
+## Pre-commit Hooks
+
+The project uses Husky for Git hooks:
+
+- **lint-staged**: Format staged files
+- **npm test**: Run test suite
+- **validate-all**: Custom validation
+
+To skip hooks (not recommended):
+
+```bash
+git commit --no-verify -m "message"
+```
+
+## Troubleshooting
+
+### Port Already in Use
+
+```bash
+# Kill process on port 3010
+lsof -ti:3010 | xargs kill -9
+```
+
+### Database Errors
+
+```bash
+# Remove database and restart
+rm -f data/todos.db
+npm run dev
+```
+
+### Type Errors
+
+```bash
+# Clean and rebuild
+rm -rf dist node_modules
+npm install
+npm run dev
+```
+
+## Next Steps
+
+- Read `DESIGN.md` for architecture details
+- Check `CLAUDE.md` for development guidelines
+- Explore test files for examples
+- Add your own features!