create-fullstack-scaffold 0.1.0

package/template/tests/e2e/websocket.spec.ts

@@ -0,0 +1,254 @@
+/**
+ * WebSocket App E2E Tests
+ *
+ * Testing WebSocket application functionality with Playwright
+ *
+ * The dev server is started automatically by global-setup.ts
+ * on a random available port.
+ */
+
+import { test, expect, type Page } from '@playwright/test'
+
+function getBaseUrl(): string {
+  return process.env.PLAYWRIGHT_TEST_BASE_URL || 'http://localhost:3010'
+}
+
+const persistenceTestInProgress = false
+
+async function waitForServerReady(baseUrl: string, timeout = 30000): Promise<void> {
+  const startTime = Date.now()
+  while (Date.now() - startTime < timeout) {
+    try {
+      const response = await fetch(`${baseUrl}/health`)
+      if (response.ok) return
+    } catch {
+      // Server not ready yet
+    }
+    await new Promise(resolve => setTimeout(resolve, 500))
+  }
+  throw new Error(`Server not ready after ${timeout}ms`)
+}
+
+async function connectWithRetry(page: Page, maxRetries = 3) {
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
+    const connectBtn = page.locator('[data-testid="connect-ws-button"]')
+    if (await connectBtn.isEnabled({ timeout: 2000 }).catch(() => false)) {
+      await connectBtn.click()
+    }
+
+    try {
+      await page.waitForSelector('[data-testid="ws-status-open"]', { timeout: 10000 })
+      return
+    } catch {
+      const disconnectBtn = page.locator('[data-testid="disconnect-ws-button"]')
+      if (
+        (await disconnectBtn.isVisible({ timeout: 1000 }).catch(() => false)) &&
+        (await disconnectBtn.isEnabled({ timeout: 500 }).catch(() => false))
+      ) {
+        await disconnectBtn.click()
+        await page.waitForTimeout(1000)
+      } else {
+        await page.waitForTimeout(1000)
+      }
+    }
+  }
+  await page.locator('[data-testid="connect-ws-button"]').click()
+  await page.waitForSelector('[data-testid="ws-status-open"]', { timeout: 15000 })
+}
+
+// Skip WebSocket tests in CI - Vite dev server WS proxy causes browser crash
+test.skip(!!process.env.CI, 'WebSocket tests crash browser in CI - Vite WS proxy unreliable')
+
+test.beforeEach(async ({ page }) => {
+  await waitForServerReady(getBaseUrl())
+
+  if (!persistenceTestInProgress) {
+    try {
+      const response = await page.request.post(`${getBaseUrl()}/api/__test__/cleanup`)
+      if (!response.ok) {
+        console.warn('Failed to cleanup database:', await response.text())
+      }
+    } catch (error) {
+      console.warn('Error during database cleanup:', error)
+    }
+  }
+
+  try {
+    await page.evaluate(() => {
+      try {
+        localStorage.clear()
+        sessionStorage.clear()
+      } catch (e) {
+        console.warn('Could not clear storage:', e)
+      }
+    })
+  } catch (error) {
+    console.warn('Error clearing storage:', error)
+  }
+
+  await page.goto(`${getBaseUrl()}/websocket`)
+  await page.waitForLoadState('load')
+  await page.waitForSelector('[data-testid="websocket-container"]', { timeout: 25000 })
+})
+
+test.afterEach(async ({ page, context }) => {
+  const pages = context.pages()
+  for (const p of pages) {
+    if (p !== page) {
+      await p.close()
+    }
+  }
+})
+
+test.describe('WebSocket App', () => {
+  test.describe('Page Load', () => {
+    test('should load websocket page successfully', async ({ page }) => {
+      await expect(page.locator('[data-testid="websocket-container"]')).toBeVisible()
+      await expect(page.locator('h1').last()).toHaveText('WebSocket Demo')
+    })
+
+    test('should display empty state when no messages', async ({ page }) => {
+      await page.waitForSelector('[data-testid="empty-state"]', { timeout: 25000 })
+      await expect(page.locator('[data-testid="empty-state"]')).toBeVisible()
+    })
+  })
+
+  test.describe('WebSocket Connection', () => {
+    test('should connect to WebSocket', async ({ page }) => {
+      await connectWithRetry(page)
+      await expect(page.locator('[data-testid="ws-status-open"]')).toBeVisible()
+    })
+
+    test('should disconnect from WebSocket', async ({ page }) => {
+      await connectWithRetry(page)
+
+      await page.click('[data-testid="disconnect-ws-button"]')
+      await page.waitForSelector('[data-testid="ws-status-closed"]', { timeout: 15000 })
+      await expect(page.locator('[data-testid="ws-status-closed"]')).toBeVisible()
+    })
+  })
+
+  test.describe('Send Messages', () => {
+    test.beforeEach(async ({ page }) => {
+      await connectWithRetry(page)
+    })
+
+    test('should send echo message', async ({ page }) => {
+      await page.fill('[data-testid="ws-message-input"]', 'Hello WebSocket')
+      await page.selectOption('[data-testid="ws-message-type-select"]', 'echo')
+      await page.click('[data-testid="send-message-button"]')
+
+      await page.waitForSelector('[data-testid="message-item"]', { timeout: 10000 })
+      const count = await page.locator('[data-testid="message-item"]').count()
+      expect(count).toBeGreaterThanOrEqual(2)
+    })
+
+    test('should send ping message', async ({ page }) => {
+      await page.selectOption('[data-testid="ws-message-type-select"]', 'ping')
+      await page.click('[data-testid="send-message-button"]')
+
+      await page.waitForSelector('[data-testid="message-item"]', { timeout: 10000 })
+      const count = await page.locator('[data-testid="message-item"]').count()
+      expect(count).toBeGreaterThanOrEqual(2)
+    })
+
+    test('should send broadcast message', async ({ page }) => {
+      await page.fill('[data-testid="ws-message-input"]', 'Broadcast message')
+      await page.selectOption('[data-testid="ws-message-type-select"]', 'broadcast')
+      await page.click('[data-testid="send-message-button"]')
+
+      await page.waitForSelector('[data-testid="message-item"]', { timeout: 10000 })
+      const count = await page.locator('[data-testid="message-item"]').count()
+      expect(count).toBeGreaterThanOrEqual(1)
+    })
+
+    test('should send notification message', async ({ page }) => {
+      await page.fill('[data-testid="ws-message-input"]', 'Notification message')
+      await page.selectOption('[data-testid="ws-message-type-select"]', 'notification')
+      await page.click('[data-testid="send-message-button"]')
+
+      await page.waitForSelector('[data-testid="message-item"]', { timeout: 10000 })
+      const count = await page.locator('[data-testid="message-item"]').count()
+      expect(count).toBeGreaterThanOrEqual(1)
+    })
+
+    test('should clear input after sending message', async ({ page }) => {
+      await page.fill('[data-testid="ws-message-input"]', 'Test message')
+      await page.selectOption('[data-testid="ws-message-type-select"]', 'echo')
+      await page.click('[data-testid="send-message-button"]')
+      await expect(page.locator('[data-testid="ws-message-input"]')).toHaveValue('')
+    })
+
+    test('should not send empty message', async ({ page }) => {
+      const initialCount = await page.locator('[data-testid="message-item"]').count()
+
+      await page.selectOption('[data-testid="ws-message-type-select"]', 'echo')
+      await expect(page.locator('[data-testid="send-message-button"]')).toBeDisabled()
+      await page.click('[data-testid="send-message-button"]', { force: true }).catch(() => {})
+
+      await page.waitForTimeout(500)
+      await expect(page.locator('[data-testid="message-item"]')).toHaveCount(initialCount)
+    })
+  })
+
+  test.describe('Clear Messages', () => {
+    test.beforeEach(async ({ page }) => {
+      await connectWithRetry(page)
+
+      await page.fill('[data-testid="ws-message-input"]', 'Test message')
+      await page.selectOption('[data-testid="ws-message-type-select"]', 'echo')
+      await page.click('[data-testid="send-message-button"]')
+      await page.waitForSelector('[data-testid="message-item"]', { timeout: 10000 })
+    })
+
+    test('should clear all messages', async ({ page }) => {
+      await page.click('[data-testid="clear-messages-button"]')
+      await expect(page.locator('[data-testid="message-item"]')).toHaveCount(0)
+      await expect(page.locator('[data-testid="empty-state"]')).toBeVisible()
+    })
+  })
+
+  test.describe('Multiple Messages', () => {
+    test.beforeEach(async ({ page }) => {
+      await connectWithRetry(page)
+    })
+
+    test('should display multiple messages', async ({ page }) => {
+      await page.fill('[data-testid="ws-message-input"]', 'Message 1')
+      await page.selectOption('[data-testid="ws-message-type-select"]', 'echo')
+      await page.click('[data-testid="send-message-button"]')
+      await page.waitForSelector('[data-testid="message-item"]', { timeout: 10000 })
+
+      await page.fill('[data-testid="ws-message-input"]', 'Message 2')
+      await page.click('[data-testid="send-message-button"]')
+      await page.waitForTimeout(1000)
+
+      const count = await page.locator('[data-testid="message-item"]').count()
+      expect(count).toBeGreaterThanOrEqual(3)
+    })
+
+    test('should display message count', async ({ page }) => {
+      await page.fill('[data-testid="ws-message-input"]', 'Message 1')
+      await page.selectOption('[data-testid="ws-message-type-select"]', 'echo')
+      await page.click('[data-testid="send-message-button"]')
+      await page.waitForSelector('[data-testid="message-item"]', { timeout: 10000 })
+
+      await expect(page.locator('[data-testid="message-count"]')).toHaveText(/Messages \(\d+\)/)
+    })
+  })
+
+  test.describe('WebSocket Status', () => {
+    test('should show open status when connected', async ({ page }) => {
+      await connectWithRetry(page)
+      await expect(page.locator('[data-testid="ws-status-open"]')).toBeVisible()
+    })
+
+    test('should show closed status when disconnected', async ({ page }) => {
+      await connectWithRetry(page)
+
+      await page.click('[data-testid="disconnect-ws-button"]')
+      await page.waitForSelector('[data-testid="ws-status-closed"]', { timeout: 15000 })
+      await expect(page.locator('[data-testid="ws-status-closed"]')).toBeVisible()
+    })
+  })
+})

package/template/tsconfig.json

@@ -0,0 +1,35 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "types": ["vitest/globals", "@cloudflare/workers-types", "bun-types"],
+
+    /* Path aliases require 'moduleResolution: "node" */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+
+    /* Path Aliases */
+    "baseUrl": ".",
+    "paths": {
+      "@shared/*": ["src/shared/*"],
+      "@client/*": ["src/client/*"],
+      "@server/*": ["src/server/*"],
+      "@admin/*": ["src/admin/*"],
+      "@cli/*": ["src/cli/*"]
+    }
+  },
+  "include": ["src", "e2e", "*.config.ts", "*.ts"]
+}

package/template/tsup.config.ts

@@ -0,0 +1,95 @@
+import { defineConfig } from 'tsup'
+import { existsSync } from 'fs'
+import { join } from 'path'
+
+const serverBuildConfigs = [
+  {
+    entry: ['src/server/entries/node.ts'],
+    outDir: 'dist/server',
+    format: 'esm' as const,
+    platform: 'node' as const,
+    target: 'node18' as const,
+    clean: false,
+    sourcemap: false,
+    minify: true,
+    external: [
+      '@libsql/client',
+      'mysql2',
+      'ws',
+      'drizzle-orm',
+      'drizzle-orm/libsql',
+      'drizzle-orm/libsql/migrator',
+      'drizzle-orm/mysql2',
+      'drizzle-orm/d1',
+      'pino',
+      'pino-pretty',
+      'dotenv',
+    ],
+    treeshake: true,
+    dts: false,
+  },
+  {
+    entry: ['src/server/entries/cloudflare.ts'],
+    outDir: 'dist/cloudflare',
+    format: 'esm' as const,
+    platform: 'neutral' as const,
+    target: 'es2022' as const,
+    clean: true,
+    sourcemap: false,
+    minify: true,
+    treeshake: true,
+    dts: false,
+    noExternal: [
+      'hono',
+      '@hono/zod-openapi',
+      '@hono/zod-validator',
+      'zod',
+      'drizzle-orm',
+      'drizzle-orm/d1',
+    ],
+    external: [
+      'pino',
+      'pino-pretty',
+      'dotenv',
+      '@libsql/client',
+      'mysql2',
+      'ws',
+      'drizzle-orm/libsql',
+      'drizzle-orm/libsql/migrator',
+      'drizzle-orm/mysql2',
+      'path',
+      'fs',
+      'crypto',
+      'http',
+      'stream',
+      'node:path',
+      'node:fs',
+      'node:crypto',
+      'node:http',
+      'node:stream',
+    ],
+    define: {
+      'process.env.NODE_ENV': '"production"',
+    },
+  },
+]
+
+// Only build CLI if CLI module is included in preset
+const cliEntryPath = join(process.cwd(), 'src/cli/index.ts')
+if (existsSync(cliEntryPath)) {
+  serverBuildConfigs.push({
+    entry: ['src/cli/index.ts'],
+    outDir: 'dist/cli',
+    format: 'esm' as const,
+    platform: 'node' as const,
+    target: 'node18' as const,
+    clean: false,
+    sourcemap: true,
+    minify: false,
+    treeshake: true,
+    dts: true,
+    external: ['hono', 'hono/client', 'commander', 'chalk', 'eslint'],
+  })
+}
+
+export default defineConfig(serverBuildConfigs)

package/template/vite-plugins.ts

@@ -0,0 +1,113 @@
+import type { Plugin } from 'vite'
+import type { IncomingMessage } from 'http'
+import type { Duplex } from 'stream'
+import http from 'http'
+
+let entryReady = false
+
+async function waitForEntry(port: number, maxRetries = 60): Promise<void> {
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      await new Promise<void>((resolve, reject) => {
+        const req = http.get(`http://localhost:${port}/health`, res => {
+          if (res.statusCode === 200) {
+            resolve()
+          } else {
+            reject(new Error(`Health check failed with status ${res.statusCode}`))
+          }
+        })
+        req.on('error', reject)
+        req.end()
+      })
+      entryReady = true
+      return
+    } catch {
+      await new Promise(resolve => setTimeout(resolve, 500))
+    }
+  }
+  console.error('[WebSocket Plugin] Failed to load entry file after retries')
+}
+
+export function websocketPlugin(): Plugin {
+  return {
+    name: 'websocket-upgrade',
+    configureServer(server) {
+      server.httpServer?.once('listening', async () => {
+        const address = server.httpServer?.address()
+        if (address && typeof address === 'object') {
+          await waitForEntry(address.port)
+        }
+      })
+
+      server.httpServer?.on(
+        'upgrade',
+        async (req: IncomingMessage, socket: Duplex, head: Buffer) => {
+          if (!req.url) return
+
+          if (!entryReady) {
+            const address = server.httpServer?.address()
+            if (address && typeof address === 'object') {
+              await waitForEntry(address.port)
+            }
+          }
+
+          try {
+            await server.ssrLoadModule('/src/server/index.ts')
+          } catch {
+            return
+          }
+
+          const runtimeModule = await server.ssrLoadModule('/src/server/core/runtime.ts')
+          const { getRuntimeAdapter } = runtimeModule
+
+          let runtime: InstanceType<
+            typeof import('./src/server/core/runtime-node').NodeRuntimeAdapter
+          > | null = null
+          try {
+            runtime = getRuntimeAdapter() as InstanceType<
+              typeof import('./src/server/core/runtime-node').NodeRuntimeAdapter
+            >
+          } catch {
+            return
+          }
+
+          const urlObj = new URL(req.url, 'http://localhost')
+          if (runtime && runtime.hasWSPath(urlObj.pathname)) {
+            const { WebSocketServer } = await import('ws')
+            const wssInstance = new WebSocketServer({ noServer: true })
+            wssInstance.handleUpgrade(req, socket, head, ws => {
+              runtime!.handleConnection(ws)
+            })
+          }
+        }
+      )
+    },
+  }
+}
+
+export function dbPlugin(): Plugin {
+  return {
+    name: 'db-bootstrap',
+    configureServer(server) {
+      server.httpServer?.once('listening', async () => {
+        try {
+          const dbModule = await server.ssrLoadModule('/src/server/db/index.ts')
+          const loggerModule = await server.ssrLoadModule('/src/server/utils/logger.ts')
+
+          const log = loggerModule.logger.bootstrap()
+          log.info({}, 'Initializing database...')
+
+          await dbModule.getDb()
+          await dbModule.runMigrations()
+
+          const dbInitModule = await server.ssrLoadModule('/src/server/db/init.ts')
+          await dbInitModule.initializeDatabase()
+
+          log.info({}, 'Database ready')
+        } catch (err) {
+          console.error('[DB Plugin] Database initialization failed:', err)
+        }
+      })
+    },
+  }
+}

package/template/vite.config.ts

@@ -0,0 +1,96 @@
+import path from 'path'
+import { existsSync } from 'fs'
+import { defineConfig } from 'vite'
+import devServer from '@hono/vite-dev-server'
+import { websocketPlugin, dbPlugin } from './vite-plugins'
+import prerender from '@prerenderer/rollup-plugin'
+import puppeteerRenderer from '@prerenderer/renderer-puppeteer'
+
+async function getPrerenderRoutes(): Promise<string[]> {
+  const staticRoutes = ['/', '/todos', '/notifications', '/websocket', '/content']
+
+  try {
+    const { createClient } = await import('@libsql/client')
+    const dbCandidates = [
+      path.resolve(process.cwd(), 'data/production.db'),
+      path.resolve(process.cwd(), 'data/app.db'),
+      path.resolve(process.cwd(), 'data/development.db'),
+    ]
+
+    for (const dbPath of dbCandidates) {
+      if (!existsSync(dbPath)) continue
+
+      const client = createClient({ url: `file:${dbPath}` })
+      try {
+        const rs = await client.execute(
+          "SELECT id FROM contents WHERE status = 'published' ORDER BY created_at DESC"
+        )
+        client.close()
+
+        if (rs.rows.length > 0) {
+          const contentRoutes = rs.rows.map(row => `/content/content-${row.id}`)
+          return [...staticRoutes, ...contentRoutes]
+        }
+      } catch {
+        client.close()
+      }
+    }
+  } catch {
+    // fallback
+  }
+
+  return staticRoutes
+}
+
+const routes = await getPrerenderRoutes()
+
+export default defineConfig({
+  server: {
+    port: 0,
+    host: '0.0.0.0',
+    hmr: {
+      overlay: true,
+    },
+  },
+  plugins: [
+    devServer({
+      entry: 'src/server/index.ts',
+      exclude: [
+        /^\/$/,
+        /^\/(@[a-zA-Z0-9_-]+|node_modules|__inspect|assets|index\.html|admin\.html|src)/,
+        /.*\.(ts|tsx|js|jsx|css|json|png|jpg|svg)$/,
+      ],
+    }),
+    websocketPlugin(),
+    dbPlugin(),
+  ],
+  build: {
+    outDir: 'dist/client',
+    rollupOptions: {
+      input: {
+        main: path.resolve(__dirname, 'index.html'),
+        admin: path.resolve(__dirname, 'admin.html'),
+      },
+      output: {
+        plugins: [
+          prerender({
+            routes,
+            renderer: new puppeteerRenderer({
+              renderAfterDocumentEvent: 'prerender-ready',
+              renderAfterTime: 5000,
+            }),
+          }),
+        ],
+      },
+    },
+  },
+  resolve: {
+    alias: {
+      '@shared': path.resolve(__dirname, 'src/shared'),
+      '@client': path.resolve(__dirname, 'src/client'),
+      '@server': path.resolve(__dirname, 'src/server'),
+      '@admin': path.resolve(__dirname, 'src/admin'),
+      '@cli': path.resolve(__dirname, 'src/cli'),
+    },
+  },
+})

package/template/vitest.config.ts

@@ -0,0 +1,53 @@
+import { defineConfig } from 'vitest/config'
+import react from '@vitejs/plugin-react'
+import { resolve } from 'node:path'
+
+export default defineConfig({
+  plugins: [react()],
+  test: {
+    globals: true,
+    environment: 'jsdom',
+    setupFiles: ['./vitest.setup.ts'],
+    include: [
+      '**/__tests__/**/*.test.ts',
+      '**/__tests__/**/*.test.tsx',
+      '**/integration/**/*.test.ts',
+    ],
+    exclude: ['**/node_modules/**', '**/dist/**'],
+    testTimeout: 60000,
+    hookTimeout: 60000,
+    env: {
+      NODE_ENV: 'test',
+      SQLITE_PATH: ':memory:',
+      ENABLE_DEV_TOKENS: 'true',
+    },
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html', 'lcov'],
+      exclude: [
+        'node_modules/**',
+        'dist/**',
+        '**/*.d.ts',
+        '**/*.config.*',
+        '**/test-setup.ts',
+        'src/client/main.tsx',
+        'src/server/entries/node.ts',
+      ],
+      thresholds: {
+        lines: 71,
+        functions: 71,
+        branches: 60,
+        statements: 71,
+      },
+    },
+  },
+  resolve: {
+    alias: {
+      '@shared': resolve(__dirname, 'src/shared'),
+      '@client': resolve(__dirname, 'src/client'),
+      '@server': resolve(__dirname, 'src/server'),
+      '@admin': resolve(__dirname, 'src/admin'),
+      '@cli': resolve(__dirname, 'src/cli'),
+    },
+  },
+})

package/template/vitest.integration.config.ts

@@ -0,0 +1,24 @@
+import { defineConfig } from 'vitest/config';
+import path from 'path';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node', // 集成测试使用 node 环境
+    setupFiles: ['./vitest.integration.setup.ts'],
+    include: ['**/integration/**/*.test.ts', '**/integration/__tests__/**/*.test.ts'],
+    exclude: ['node_modules/**', 'dist/**'],
+    env: {
+      NODE_ENV: 'test',
+      SQLITE_PATH: ':memory:',
+      ENABLE_DEV_TOKENS: 'true',
+    },
+  },
+  resolve: {
+    alias: {
+      '@shared': path.resolve(__dirname, './src/shared'),
+      '@client': path.resolve(__dirname, './src/client'),
+      '@server': path.resolve(__dirname, './src/server'),
+    },
+  },
+});

package/template/vitest.integration.setup.ts

@@ -0,0 +1,22 @@
+/**
+ * 集成测试全局设置
+ *
+ * 为集成测试设置真实的数据库环境
+ * 使用 Node.js 原生 node:sqlite 模块
+ */
+
+import { beforeAll } from 'vitest'
+
+beforeAll(async () => {
+  // 设置测试环境变量（如果未从外部传入）
+  if (!process.env.DB_PATH) {
+    process.env.DB_PATH = ':memory:' // 内存数据库
+  }
+  if (!process.env.NODE_ENV) {
+    Object.defineProperty(process.env, 'NODE_ENV', {
+      value: 'test',
+      writable: true,
+      configurable: true,
+    })
+  }
+})