create-fullstack-scaffold 0.1.0

package/template/src/client/stores/notificationStore.ts

@@ -0,0 +1,199 @@
+import { create } from 'zustand'
+import { apiClient } from '@client/services/apiClient'
+import type {
+  AppNotification,
+  CreateNotificationInput,
+  SSEClient,
+  AppSSEProtocol,
+} from '@shared/schemas'
+
+interface NotificationState {
+  notifications: AppNotification[]
+  unreadCount: number
+  loading: boolean
+  error: string | null
+  sseConnected: boolean
+
+  fetchNotifications: (unreadOnly?: boolean) => Promise<void>
+  createNotification: (input: CreateNotificationInput) => Promise<void>
+  markAsRead: (id: string) => Promise<void>
+  markAllAsRead: () => Promise<void>
+  deleteNotification: (id: string) => Promise<void>
+  fetchUnreadCount: () => Promise<void>
+  connectSSE: () => Promise<void>
+  disconnectSSE: () => void
+}
+
+let sseClient: SSEClient<AppSSEProtocol> | null = null
+
+export const useNotificationStore = create<NotificationState>(set => ({
+  notifications: [],
+  unreadCount: 0,
+  loading: false,
+  error: null,
+  sseConnected: false,
+
+  fetchNotifications: async (unreadOnly = false) => {
+    set({ loading: true, error: null })
+    try {
+      const response = await apiClient.api.notifications.$get({
+        query: { unreadOnly: String(unreadOnly) },
+      })
+      const result = await response.json()
+      if (result.success) {
+        set({ notifications: result.data.items, loading: false })
+      } else {
+        set({ error: result.error, loading: false })
+      }
+    } catch (error) {
+      set({
+        error: error instanceof Error ? error.message : 'Unknown error',
+        loading: false,
+      })
+    }
+  },
+
+  createNotification: async input => {
+    set({ loading: true, error: null })
+    try {
+      const response = await apiClient.api.notifications.$post({
+        json: input,
+      })
+      const result = await response.json()
+      if (result.success) {
+        set(state => ({
+          notifications: [result.data, ...state.notifications],
+          unreadCount: state.unreadCount + 1,
+          loading: false,
+        }))
+      } else {
+        set({ error: result.error, loading: false })
+      }
+    } catch (error) {
+      set({
+        error: error instanceof Error ? error.message : 'Unknown error',
+        loading: false,
+      })
+    }
+  },
+
+  markAsRead: async (id: string) => {
+    try {
+      const response = await apiClient.api.notifications[':id'].read.$patch({
+        param: { id },
+      })
+      const result = await response.json()
+      if (result.success) {
+        set(state => ({
+          notifications: state.notifications.map(n => (n.id === id ? { ...n, read: true } : n)),
+          unreadCount: Math.max(0, state.unreadCount - 1),
+        }))
+      }
+    } catch (error) {
+      console.error('Failed to mark as read:', error)
+    }
+  },
+
+  markAllAsRead: async () => {
+    try {
+      const response = await apiClient.api.notifications['read-all'].$patch()
+      const result = await response.json()
+      if (result.success) {
+        set(state => ({
+          notifications: state.notifications.map(n => ({ ...n, read: true })),
+          unreadCount: 0,
+        }))
+      }
+    } catch (error) {
+      console.error('Failed to mark all as read:', error)
+    }
+  },
+
+  deleteNotification: async (id: string) => {
+    try {
+      const response = await apiClient.api.notifications[':id'].$delete({
+        param: { id },
+      })
+      const result = await response.json()
+      if (result.success) {
+        set(state => {
+          const notification = state.notifications.find(n => n.id === id)
+          return {
+            notifications: state.notifications.filter(n => n.id !== id),
+            unreadCount:
+              notification && !notification.read ? state.unreadCount - 1 : state.unreadCount,
+          }
+        })
+      }
+    } catch (error) {
+      console.error('Failed to delete:', error)
+    }
+  },
+
+  fetchUnreadCount: async () => {
+    try {
+      const response = await apiClient.api.notifications['unread-count'].$get()
+      const result = await response.json()
+      if (result.success) {
+        set({ unreadCount: result.data.count })
+      }
+    } catch (error) {
+      console.error('Failed to fetch unread count:', error)
+    }
+  },
+
+  connectSSE: async () => {
+    if (sseClient) return
+
+    try {
+      const conn = apiClient.api.notifications.stream.$sse()
+
+      conn.onStatusChange(status => {
+        if (import.meta.env.DEV) {
+          console.log('[SSE] Status changed:', status)
+        }
+        set({ sseConnected: status === 'open' })
+      })
+
+      conn.on('connected', payload => {
+        if (import.meta.env.DEV) {
+          console.log('[SSE] Connected:', payload)
+        }
+      })
+
+      conn.on('notification', notification => {
+        if (import.meta.env.DEV) {
+          console.log('[SSE] Received notification:', notification)
+        }
+        set(state => {
+          if (state.notifications.some(n => n.id === notification.id)) {
+            return state
+          }
+          return {
+            notifications: [notification, ...state.notifications],
+            unreadCount: notification.read ? state.unreadCount : state.unreadCount + 1,
+          }
+        })
+      })
+
+      conn.onError(error => {
+        console.error('[SSE] Error:', error)
+      })
+
+      sseClient = conn
+      if (import.meta.env.DEV) {
+        console.log('[SSE] Client initialized')
+      }
+    } catch (error) {
+      console.error('[SSE] Failed to connect:', error)
+    }
+  },
+
+  disconnectSSE: () => {
+    if (sseClient) {
+      sseClient.abort()
+      sseClient = null
+      set({ sseConnected: false })
+    }
+  },
+}))

package/template/src/client/stores/todoStore.ts

@@ -0,0 +1,207 @@
+import { create } from 'zustand'
+import { apiClient } from '@client/services/apiClient'
+import type { Todo, CreateTodoInput, UpdateTodoInput, TodoAttachment } from '@shared/schemas'
+
+interface TodoState {
+  todos: Todo[]
+  loading: boolean
+  error: string | null
+  attachments: Map<number, TodoAttachment[]>
+
+  fetchTodos: () => Promise<void>
+  createTodo: (input: CreateTodoInput) => Promise<void>
+  updateTodo: (id: number, input: UpdateTodoInput) => Promise<void>
+  deleteTodo: (id: number) => Promise<void>
+  uploadAttachment: (todoId: number, file: File) => Promise<TodoAttachment | null>
+  fetchAttachments: (todoId: number) => Promise<void>
+  deleteAttachment: (todoId: number, attachmentId: number) => Promise<void>
+  setError: (error: string | null) => void
+}
+
+export const useTodoStore = create<TodoState>(set => ({
+  todos: [],
+  loading: false,
+  error: null,
+  attachments: new Map(),
+
+  fetchTodos: async () => {
+    set({ loading: true, error: null })
+    try {
+      const response = await apiClient.api.todos.$get()
+      const result = await response.json()
+      if (result.success) {
+        const data = result.data as Todo[] | { items: Todo[] }
+        const items = Array.isArray(data) ? data : data.items || []
+        set({ todos: items, loading: false })
+      } else {
+        set({ error: result.error, loading: false })
+      }
+    } catch (error) {
+      set({
+        error: error instanceof Error ? error.message : 'Unknown error',
+        loading: false,
+      })
+    }
+  },
+
+  createTodo: async (input: CreateTodoInput) => {
+    set({ loading: true, error: null })
+    try {
+      const response = await apiClient.api.todos.$post({
+        json: input,
+      })
+      const result = await response.json()
+      if (result.success) {
+        set(state => ({
+          todos: [result.data, ...state.todos],
+          loading: false,
+        }))
+      } else {
+        set({ error: result.error, loading: false })
+      }
+    } catch (error) {
+      set({
+        error: error instanceof Error ? error.message : 'Unknown error',
+        loading: false,
+      })
+    }
+  },
+
+  updateTodo: async (id: number, input: UpdateTodoInput) => {
+    set({ loading: true, error: null })
+    try {
+      const response = await apiClient.api.todos[':id'].$put({
+        param: { id: id.toString() },
+        json: input,
+      })
+      const result = await response.json()
+      if (result.success) {
+        set(state => ({
+          todos: state.todos.map(todo => (todo.id === id ? result.data : todo)),
+          loading: false,
+        }))
+      } else {
+        set({ error: result.error, loading: false })
+      }
+    } catch (error) {
+      set({
+        error: error instanceof Error ? error.message : 'Unknown error',
+        loading: false,
+      })
+    }
+  },
+
+  deleteTodo: async (id: number) => {
+    set({ loading: true, error: null })
+    try {
+      const response = await apiClient.api.todos[':id'].$delete({
+        param: { id: id.toString() },
+      })
+      const result = await response.json()
+      if (result.success) {
+        set(state => {
+          const newAttachments = new Map(state.attachments)
+          newAttachments.delete(id)
+          return {
+            todos: state.todos.filter(todo => todo.id !== id),
+            attachments: newAttachments,
+            loading: false,
+          }
+        })
+      } else {
+        set({ error: result.error, loading: false })
+      }
+    } catch (error) {
+      set({
+        error: error instanceof Error ? error.message : 'Unknown error',
+        loading: false,
+      })
+    }
+  },
+
+  uploadAttachment: async (todoId: number, file: File): Promise<TodoAttachment | null> => {
+    set({ loading: true, error: null })
+    try {
+      const response = await apiClient.api.todos[':id'].attachments.$post({
+        param: { id: todoId.toString() },
+        form: { file },
+      })
+
+      const result = (await response.json()) as {
+        success: boolean
+        data?: TodoAttachment
+        error?: string
+      }
+      if (result.success && result.data) {
+        set(state => {
+          const newAttachments = new Map(state.attachments)
+          const existing = newAttachments.get(todoId) || []
+          newAttachments.set(todoId, [...existing, result.data!])
+          return { attachments: newAttachments, loading: false }
+        })
+        return result.data
+      } else {
+        set({ error: result.error || 'Upload failed', loading: false })
+        return null
+      }
+    } catch (error) {
+      set({
+        error: error instanceof Error ? error.message : 'Unknown error',
+        loading: false,
+      })
+      return null
+    }
+  },
+
+  fetchAttachments: async (todoId: number) => {
+    try {
+      const response = await apiClient.api.todos[':id'].attachments.$get({
+        param: { id: todoId.toString() },
+      })
+      const result = await response.json()
+      if (result.success) {
+        set(state => {
+          const newAttachments = new Map(state.attachments)
+          const data = result.data as TodoAttachment[] | { items: TodoAttachment[] }
+          const items = Array.isArray(data) ? data : data.items || []
+          newAttachments.set(todoId, items)
+          return { attachments: newAttachments }
+        })
+      }
+    } catch (error) {
+      console.error('Failed to fetch attachments:', error)
+    }
+  },
+
+  deleteAttachment: async (todoId: number, attachmentId: number) => {
+    set({ loading: true, error: null })
+    try {
+      const response = await apiClient.api.todos[':todoId'].attachments[':attachmentId'].$delete({
+        param: { todoId: todoId.toString(), attachmentId: attachmentId.toString() },
+      })
+      const result = await response.json()
+      if (result.success) {
+        set(state => {
+          const newAttachments = new Map(state.attachments)
+          const existing = newAttachments.get(todoId) || []
+          newAttachments.set(
+            todoId,
+            existing.filter(a => a.id !== attachmentId)
+          )
+          return { attachments: newAttachments, loading: false }
+        })
+      } else {
+        set({ error: result.error, loading: false })
+      }
+    } catch (error) {
+      set({
+        error: error instanceof Error ? error.message : 'Unknown error',
+        loading: false,
+      })
+    }
+  },
+
+  setError: (error: string | null) => {
+    set({ error })
+  },
+}))

package/template/src/server/__tests__/integration/todos-api.test.ts

@@ -0,0 +1,138 @@
+import { describe, it, expect, beforeAll, afterAll, beforeEach, afterEach } from 'vitest'
+import { createTestClient } from '@server/test-utils/test-client'
+import { getDb } from '@server/db'
+import { setupTestDatabase, cleanupTestDatabase } from '@server/db/test-setup'
+
+describe('Integration: Todos API (Real Database)', () => {
+  const authHeaders = { Authorization: 'Bearer admin-token' }
+
+  beforeAll(async () => {
+    await setupTestDatabase()
+    const db = await getDb()
+    expect(db).toBeDefined()
+  })
+
+  afterAll(async () => {
+    await cleanupTestDatabase()
+  })
+
+  beforeEach(async () => {
+    await cleanupTestDatabase()
+  })
+
+  afterEach(async () => {
+    await cleanupTestDatabase()
+  })
+
+  describe('Full CRUD Flow', () => {
+    it('should handle complete todo lifecycle', async () => {
+      const client = createTestClient(undefined, { headers: authHeaders })
+
+      const listRes = await client.api.todos.$get({ headers: authHeaders })
+      const listData = await listRes.json()
+      expect(listData).toMatchObject({ success: true, data: [] })
+
+      const createRes = await client.api.todos.$post(
+        {
+          json: { title: 'Integration Todo', description: 'Full test' },
+        },
+        { headers: authHeaders }
+      )
+      expect(createRes.status).toBe(201)
+      const created = await createRes.json()
+      expect(created.success).toBe(true)
+      if (created.success && 'data' in created) {
+        expect(created.data.title).toBe('Integration Todo')
+
+        const readRes = await client.api.todos[':id'].$get(
+          {
+            param: { id: String(created.data.id) },
+          },
+          { headers: authHeaders }
+        )
+        const readData = await readRes.json()
+        expect(readData.success).toBe(true)
+
+        const updateRes = await client.api.todos[':id'].$put(
+          {
+            param: { id: String(created.data.id) },
+            json: { status: 'completed' },
+          },
+          { headers: authHeaders }
+        )
+        const updated = await updateRes.json()
+        expect(updated.success).toBe(true)
+        if (updated.success && 'data' in updated) {
+          expect(updated.data.status).toBe('completed')
+        }
+
+        const deleteRes = await client.api.todos[':id'].$delete(
+          {
+            param: { id: String(created.data.id) },
+          },
+          { headers: authHeaders }
+        )
+        const deleted = await deleteRes.json()
+        expect(deleted.success).toBe(true)
+
+        const verifyRes = await client.api.todos[':id'].$get(
+          {
+            param: { id: String(created.data.id) },
+          },
+          { headers: authHeaders }
+        )
+        expect(verifyRes.status).toBe(404)
+      }
+    })
+
+    it('should handle concurrent requests', async () => {
+      const client = createTestClient(undefined, { headers: authHeaders })
+
+      const promises = Array.from({ length: 10 }, (_, i) =>
+        client.api.todos.$post(
+          {
+            json: { title: `Concurrent Todo ${i}` },
+          },
+          { headers: authHeaders }
+        )
+      )
+
+      const results = await Promise.all(promises)
+      results.forEach((res: { status: number }) => {
+        expect(res.status).toBe(201)
+      })
+
+      const listRes = await client.api.todos.$get({ headers: authHeaders })
+      const listData = await listRes.json()
+      if (listData.success && 'data' in listData) {
+        expect(listData.data).toHaveLength(10)
+      }
+    })
+  })
+
+  describe('Edge Cases', () => {
+    it('should return 404 for non-existent todo', async () => {
+      const client = createTestClient(undefined, { headers: authHeaders })
+
+      const res = await client.api.todos[':id'].$get(
+        {
+          param: { id: '99999' },
+        },
+        { headers: authHeaders }
+      )
+      expect(res.status).toBe(404)
+    })
+
+    it('should reject invalid todo data', async () => {
+      const client = createTestClient(undefined, { headers: authHeaders })
+
+      const res = await client.api.todos.$post(
+        {
+          json: { title: '' },
+        },
+        { headers: authHeaders }
+      )
+      expect(res.status).toBe(400)
+    })
+  })
+})

package/template/src/server/app.ts

@@ -0,0 +1,105 @@
+import { OpenAPIHono } from '@hono/zod-openapi'
+
+import { HTTPException } from 'hono/http-exception'
+import type { ContentfulStatusCode } from 'hono/utils/http-status'
+import { ZodError } from 'zod'
+import type { AppBindings, CreateAppOptions } from './types/bindings'
+import { AppError } from './utils/app-error'
+import { autoRegisterRealtime } from './core/realtime-scanner'
+import { corsMiddleware, loggerMiddleware, errorHandlerMiddleware } from './middleware'
+import { realtimeEnvMiddleware } from './middleware/realtime-env'
+import { captchaMiddleware } from './middleware/captcha'
+import { auditLogMiddleware } from './middleware/audit-log'
+import { createModuleLoggerSync } from './utils/logger'
+import { adminApiRoutes, clientApiRoutes } from './route-registry'
+import { fileRoutes } from './module-file/routes/file-routes'
+
+export { type AppBindings, type CreateAppOptions } from './types/bindings'
+
+export function createApp<T extends AppBindings = AppBindings>(_options: CreateAppOptions = {}) {
+  const app = new OpenAPIHono<{ Bindings: T }>()
+    .use('*', errorHandlerMiddleware())
+    .use('*', loggerMiddleware())
+    .use('*', corsMiddleware())
+    .use('*', realtimeEnvMiddleware())
+    .use('/api/*', auditLogMiddleware())
+    .use(
+      '/api/admin/*',
+      captchaMiddleware({
+        maxRequests: 20,
+        windowMs: 60000,
+      })
+    )
+    .route('/', clientApiRoutes)
+    .route('/', adminApiRoutes)
+    .route('/files', fileRoutes)
+    .get('/health', async c => {
+      try {
+        const { getDb } = await import('./db')
+        await getDb()
+        return c.json({ status: 'ok', timestamp: new Date().toISOString(), db: 'connected' })
+      } catch {
+        return c.json({ status: 'ok', timestamp: new Date().toISOString(), db: 'not configured' })
+      }
+    })
+    .post('/api/__test__/cleanup', async c => {
+      try {
+        const { cleanupTestDatabase } = await import('./db/test-setup')
+        await cleanupTestDatabase()
+        return c.json({ success: true as const, message: 'Database cleaned up' })
+      } catch (error) {
+        console.error('Error during database cleanup:', error)
+        return c.json({ success: false as const, message: 'Failed to cleanup database' }, 500)
+      }
+    })
+
+  autoRegisterRealtime(app as unknown as Parameters<typeof autoRegisterRealtime>[0])
+
+  // Last-resort error handler for framework-level errors (e.g. 404 Not Found).
+  // The canonical error handler is errorHandlerMiddleware (middleware/error-handler.ts).
+  app.onError((err, c) => {
+    const log = createModuleLoggerSync('api')
+    c.res.headers.set('Content-Type', 'application/json')
+
+    if (AppError.isAppError(err)) {
+      return c.json(
+        {
+          success: false as const,
+          error: err.message,
+          status: err.statusCode,
+          details: err.details,
+        },
+        err.statusCode as ContentfulStatusCode
+      )
+    }
+
+    if (err instanceof HTTPException) {
+      return c.json(
+        { success: false as const, error: err.message, status: err.status },
+        err.status as ContentfulStatusCode
+      )
+    }
+
+    if (err instanceof ZodError) {
+      const details = err.issues.map(issue => ({
+        field: issue.path.join('.'),
+        message: issue.message,
+      }))
+      return c.json(
+        { success: false as const, error: 'Validation failed', status: 400, details },
+        400
+      )
+    }
+
+    log.error({ err, path: c.req.path }, 'Unhandled error')
+    return c.json(
+      { success: false as const, error: err.message || 'Internal server error', status: 500 },
+      500
+    )
+  })
+
+  return app
+}
+export type AdminApiType = typeof adminApiRoutes
+export type ClientApiType = typeof clientApiRoutes
+export type AppType = ReturnType<typeof createApp>