create-fullstack-scaffold 0.1.0

package/template/drizzle/meta/_journal.json

@@ -0,0 +1,27 @@
+{
+  "version": "7",
+  "dialect": "sqlite",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "6",
+      "when": 1773459507461,
+      "tag": "0000_rainy_boomer",
+      "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "6",
+      "when": 1746400000000,
+      "tag": "0001_add_todo_attachments",
+      "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "6",
+      "when": 1778211178500,
+      "tag": "0002_chilly_magneto",
+      "breakpoints": true
+    }
+  ]
+}

package/template/drizzle.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from 'drizzle-kit';
+import { getDatabaseConfig } from './src/server/db/config';
+
+const config = getDatabaseConfig();
+
+export default defineConfig({
+  schema: './src/server/db/schema/index.ts',
+  out: './drizzle',
+  dialect: 'sqlite',
+  dbCredentials: {
+    url: config.sqlitePath || './data/app.db',
+  },
+});

package/template/eslint-rules/README-no-middleware-in-routes.md

@@ -0,0 +1,154 @@
+# ESLint 规则：禁止在路由文件中使用中间件
+
+## 📋 规则说明
+
+**规则名称**: `no-middleware-in-routes`  
+**类型**: Problem  
+**严重程度**: Error
+
+## 🎯 目的
+
+防止在路由文件中使用 `.use()` 方法应用中间件，因为这会导致 TypeScript 类型推导丢失。
+
+## 📚 背景
+
+在 Hono + OpenAPI 项目中，中间件的应用位置会影响类型推导：
+
+```typescript
+// 类型推导链
+OpenAPIHono
+  ↓ .use()
+Hono (丢失 OpenAPI 类型)
+  ↓ .openapi() ❌ 类型错误
+```
+
+## ✅ 正确用法
+
+### 1️⃣ 全局中间件 - 在 `app.ts` 中应用
+
+适用于所有路由或一组路由：
+
+```typescript
+// src/server/app.ts
+export function createApp() {
+  const app = new OpenAPIHono()
+    .use('*', errorHandlerMiddleware())
+    .use('/api/admin/*', captchaMiddleware()) // ✅ 全局中间件
+    .route('/api', adminRoutes)
+  return app
+}
+```
+
+### 2️⃣ 路由级中间件 - 在路由定义中配置
+
+适用于单个路由：
+
+```typescript
+// src/server/module-admin/routes/admin-routes.ts
+const getStatsRoute = createRoute({
+  method: 'get',
+  path: '/admin/stats',
+  middleware: [authMiddleware({ requiredRole: 'admin' })], // ✅ 路由级中间件
+  responses: {
+    200: successResponse(SystemStatsSchema, '获取统计数据'),
+    401: errorResponse('未授权'),
+  },
+})
+
+export const adminRoutes = new OpenAPIHono().openapi(getStatsRoute, async c => {
+  // 路由处理逻辑
+})
+```
+
+## ❌ 错误用法
+
+在路由文件中使用 `.use()` 方法：
+
+```typescript
+// src/server/module-admin/routes/admin-routes.ts
+export const adminRoutes = new OpenAPIHono()
+  .use('*', captchaMiddleware())  // ❌ 会导致类型推导丢失
+  .openapi(getStatsRoute, async c => { ... })  // ❌ 类型错误
+```
+
+## 🔍 检测范围
+
+规则会检测以下文件：
+
+- 文件路径包含 `/routes/`
+- 文件名以 `-routes.ts` 结尾
+- 不是 `app.ts` 文件
+
+**例外情况**：
+
+- ✅ 路由定义中的 `middleware: [...]` 字段是允许的
+- ❌ 在路由实例上调用 `.use()` 方法是禁止的
+
+## 📖 错误提示
+
+当检测到违规时，ESLint 会显示以下错误：
+
+```
+🚫 禁止在路由文件中使用 .use() 应用中间件。
+
+❌ 错误示例：
+   export const adminRoutes = new OpenAPIHono()
+     .use("*", captchaMiddleware())  // ❌ 会导致类型推导丢失
+     .openapi(getStatsRoute, ...)
+
+✅ 正确示例：
+
+1️⃣ 全局中间件 - 在 app.ts 中应用：
+   // src/server/app.ts
+   export function createApp() {
+     const app = new OpenAPIHono()
+       .use("/api/admin/*", captchaMiddleware())  // ✅ 全局中间件
+       .route("/api", adminRoutes)
+     return app
+   }
+
+2️⃣ 路由级中间件 - 在路由定义中配置：
+   // src/server/module-admin/routes/admin-routes.ts
+   const getStatsRoute = createRoute({
+     method: "get",
+     path: "/admin/stats",
+     middleware: [authMiddleware({ requiredRole: "admin" })],  // ✅ 路由级中间件
+     responses: { ... }
+   })
+
+📖 详细说明请查看：.claude/rules/20-server-api.md#中间件应用位置重要
+```
+
+## 📊 中间件应用位置对比
+
+| 中间件类型       | 应用位置 | 作用范围           | 示例                                        |
+| ---------------- | -------- | ------------------ | ------------------------------------------- |
+| **全局中间件**   | `app.ts` | 所有路由或一组路由 | `.use('/api/admin/*', captchaMiddleware())` |
+| **路由级中间件** | 路由定义 | 单个路由           | `middleware: [authMiddleware()]`            |
+
+## 🔧 配置
+
+规则已在 `eslint.config.js` 中配置：
+
+```javascript
+{
+  files: ['src/server/**/*.ts'],
+  rules: {
+    'local-rules/no-middleware-in-routes': 'error',
+  },
+}
+```
+
+## 📝 相关文档
+
+- [Server API 规范](../.claude/rules/00-project-config.md)
+- [API 类型推导规范](../.claude/rules/10-api-type-inference.md)
+
+## 🧪 测试
+
+规则已通过以下测试：
+
+- ✅ 在 `app.ts` 中使用 `.use()` - 不报错
+- ✅ 在路由文件中使用 `.openapi()` - 不报错
+- ✅ 在路由定义中使用 `middleware: [...]` - 不报错
+- ❌ 在路由文件中使用 `.use()` - 报错

package/template/eslint-rules/__tests__/enforce-valid-method.test.ts

@@ -0,0 +1,251 @@
+import { RuleTester } from 'eslint'
+import { enforceValidMethod } from '../enforce-valid-method.js'
+
+const ruleTester = new RuleTester({
+  languageOptions: {
+    ecmaVersion: 2020,
+    sourceType: 'module',
+  },
+})
+
+ruleTester.run('enforce-valid-method', enforceValidMethod, {
+  valid: [
+    {
+      filename: 'src/server/module-todos/routes/todos-routes.ts',
+      code: `
+import { createRoute, z } from '@hono/zod-openapi'
+import { OpenAPIHono } from '@hono/zod-openapi'
+
+const createRouteDef = createRoute({
+  method: 'post',
+  path: '/todos',
+  request: {
+    body: {
+      content: { 'application/json': { schema: z.object({ name: z.string() }) } },
+    },
+  },
+  responses: { 200: { description: 'OK' } },
+})
+
+export const routes = new OpenAPIHono()
+  .openapi(createRouteDef, async c => {
+    const data = c.req.valid('json')
+    return c.json({ data })
+  })
+`,
+    },
+    {
+      filename: 'src/server/module-todos/routes/todos-routes.ts',
+      code: `
+import { createRoute, z } from '@hono/zod-openapi'
+import { OpenAPIHono } from '@hono/zod-openapi'
+
+const getRoute = createRoute({
+  method: 'get',
+  path: '/todos/{id}',
+  request: {
+    params: z.object({ id: z.string() }),
+  },
+  responses: { 200: { description: 'OK' } },
+})
+
+export const routes = new OpenAPIHono()
+  .openapi(getRoute, async c => {
+    const { id } = c.req.valid('param')
+    return c.json({ id })
+  })
+`,
+    },
+    {
+      filename: 'src/server/module-todos/routes/todos-routes.ts',
+      code: `
+import { createRoute, z } from '@hono/zod-openapi'
+import { OpenAPIHono } from '@hono/zod-openapi'
+
+const listRoute = createRoute({
+  method: 'get',
+  path: '/todos',
+  request: {
+    query: z.object({ page: z.string().optional() }),
+  },
+  responses: { 200: { description: 'OK' } },
+})
+
+export const routes = new OpenAPIHono()
+  .openapi(listRoute, async c => {
+    const query = c.req.valid('query')
+    return c.json({ query })
+  })
+`,
+    },
+    {
+      filename: 'src/server/module-todos/routes/todos-routes.ts',
+      code: `
+import { createRoute, z } from '@hono/zod-openapi'
+import { OpenAPIHono } from '@hono/zod-openapi'
+
+const updateRoute = createRoute({
+  method: 'put',
+  path: '/todos/{id}',
+  request: {
+    params: z.object({ id: z.string() }),
+    body: {
+      content: { 'application/json': { schema: z.object({ name: z.string() }) } },
+    },
+  },
+  responses: { 200: { description: 'OK' } },
+})
+
+export const routes = new OpenAPIHono()
+  .openapi(updateRoute, async c => {
+    const { id } = c.req.valid('param')
+    const data = c.req.valid('json')
+    return c.json({ id, data })
+  })
+`,
+    },
+    {
+      filename: 'src/server/module-todos/routes/todos-routes.ts',
+      code: `
+import { createRoute, z } from '@hono/zod-openapi'
+import { OpenAPIHono } from '@hono/zod-openapi'
+
+const noSchemaRoute = createRoute({
+  method: 'get',
+  path: '/health',
+  responses: { 200: { description: 'OK' } },
+})
+
+export const routes = new OpenAPIHono()
+  .openapi(noSchemaRoute, async c => {
+    return c.json({ status: 'ok' })
+  })
+`,
+    },
+  ],
+  invalid: [
+    {
+      filename: 'src/server/module-todos/routes/todos-routes.ts',
+      code: `
+import { createRoute, z } from '@hono/zod-openapi'
+import { OpenAPIHono } from '@hono/zod-openapi'
+
+const createRouteDef = createRoute({
+  method: 'post',
+  path: '/todos',
+  request: {
+    body: {
+      content: { 'application/json': { schema: z.object({ name: z.string() }) } },
+    },
+  },
+  responses: { 200: { description: 'OK' } },
+})
+
+export const routes = new OpenAPIHono()
+  .openapi(createRouteDef, async c => {
+    const data = await c.req.json()
+    return c.json({ data })
+  })
+`,
+      errors: [{ messageId: 'forbiddenRawMethod' }],
+    },
+    {
+      filename: 'src/server/module-todos/routes/todos-routes.ts',
+      code: `
+import { createRoute, z } from '@hono/zod-openapi'
+import { OpenAPIHono } from '@hono/zod-openapi'
+
+const getRoute = createRoute({
+  method: 'get',
+  path: '/todos/{id}',
+  request: {
+    params: z.object({ id: z.string() }),
+  },
+  responses: { 200: { description: 'OK' } },
+})
+
+export const routes = new OpenAPIHono()
+  .openapi(getRoute, async c => {
+    const id = c.req.param('id')
+    return c.json({ id })
+  })
+`,
+      errors: [{ messageId: 'forbiddenRawMethod' }],
+    },
+    {
+      filename: 'src/server/module-todos/routes/todos-routes.ts',
+      code: `
+import { createRoute, z } from '@hono/zod-openapi'
+import { OpenAPIHono } from '@hono/zod-openapi'
+
+const listRoute = createRoute({
+  method: 'get',
+  path: '/todos',
+  request: {
+    query: z.object({ page: z.string().optional() }),
+  },
+  responses: { 200: { description: 'OK' } },
+})
+
+export const routes = new OpenAPIHono()
+  .openapi(listRoute, async c => {
+    const page = c.req.query('page')
+    return c.json({ page })
+  })
+`,
+      errors: [{ messageId: 'forbiddenRawMethod' }],
+    },
+    {
+      filename: 'src/server/module-todos/routes/todos-routes.ts',
+      code: `
+import { createRoute, z } from '@hono/zod-openapi'
+import { OpenAPIHono } from '@hono/zod-openapi'
+
+const createRouteDef = createRoute({
+  method: 'post',
+  path: '/todos',
+  request: {
+    body: {
+      content: { 'application/json': { schema: z.object({ name: z.string() }) } },
+    },
+  },
+  responses: { 200: { description: 'OK' } },
+})
+
+export const routes = new OpenAPIHono()
+  .openapi(createRouteDef, async c => {
+    return c.json({ status: 'ok' })
+  })
+`,
+      errors: [{ messageId: 'unusedSchema' }],
+    },
+    {
+      filename: 'src/server/module-todos/routes/todos-routes.ts',
+      code: `
+import { createRoute, z } from '@hono/zod-openapi'
+import { OpenAPIHono } from '@hono/zod-openapi'
+
+const updateRoute = createRoute({
+  method: 'put',
+  path: '/todos/{id}',
+  request: {
+    params: z.object({ id: z.string() }),
+    body: {
+      content: { 'application/json': { schema: z.object({ name: z.string() }) } },
+    },
+  },
+  responses: { 200: { description: 'OK' } },
+})
+
+export const routes = new OpenAPIHono()
+  .openapi(updateRoute, async c => {
+    const { id } = c.req.valid('param')
+    return c.json({ id })
+  })
+`,
+      errors: [{ messageId: 'unusedSchema' }],
+    },
+  ],
+})
+
+console.log('enforce-valid-method tests passed!')

package/template/eslint-rules/__tests__/layer-boundary.test.ts

@@ -0,0 +1,102 @@
+import { RuleTester } from 'eslint'
+import { layerBoundary } from '../layer-boundary.js'
+
+const ruleTester = new RuleTester({
+  languageOptions: {
+    ecmaVersion: 2020,
+    sourceType: 'module',
+  },
+})
+
+// 测试1: 业务层导入框架内部文件应该报错
+ruleTester.run('layer-boundary - import framework internal files', layerBoundary, {
+  valid: [],
+  invalid: [
+    {
+      code: `import { WSClientImpl } from '@shared/core/ws-client'`,
+      filename: '/project/src/shared/modules/chat/index.ts',
+      errors: [{ messageId: 'importFrameworkInternal' }],
+    },
+    {
+      code: `import { SSEClientImpl } from '@shared/core/sse-client'`,
+      filename: '/project/src/server/module-chat/services/chat.ts',
+      errors: [{ messageId: 'importFrameworkInternal' }],
+    },
+    {
+      code: `import { runtime } from '@server/core/runtime'`,
+      filename: '/project/src/client/stores/chatStore.ts',
+      errors: [{ messageId: 'importFrameworkInternal' }],
+    },
+  ],
+})
+
+// 测试2: 业务层导入框架层需要注释
+ruleTester.run('layer-boundary - import framework without comment', layerBoundary, {
+  valid: [],
+  invalid: [
+    {
+      code: `import { createTypedRuntime } from '@server/core/typed-runtime'`,
+      filename: '/project/src/server/module-chat/services/chat.ts',
+      errors: [{ messageId: 'missingFrameworkImportComment' }],
+    },
+  ],
+})
+
+// 测试3: 业务层导入框架层带注释应该通过
+ruleTester.run('layer-boundary - import framework with comment', layerBoundary, {
+  valid: [
+    {
+      code: `// @framework-import 用于创建类型安全的 WebSocket runtime
+import { createTypedRuntime } from '@server/core/typed-runtime'`,
+      filename: '/project/src/server/module-chat/services/chat.ts',
+    },
+  ],
+  invalid: [],
+})
+
+// 测试4: 业务层修改框架层代码应该报错
+ruleTester.run('layer-boundary - modify framework code', layerBoundary, {
+  valid: [],
+  invalid: [
+    {
+      code: `runtime.registerRPC('echo', handler)`,
+      filename: '/project/src/server/module-chat/services/chat.ts',
+      errors: [{ messageId: 'modifyFrameworkCode' }],
+    },
+    {
+      code: `runtime.broadcast('notification', data)`,
+      filename: '/project/src/client/stores/chatStore.ts',
+      errors: [{ messageId: 'modifyFrameworkCode' }],
+    },
+  ],
+})
+
+// 测试5: 业务层修改框架层代码带注释应该通过
+ruleTester.run('layer-boundary - modify framework with comment', layerBoundary, {
+  valid: [
+    {
+      code: `// @framework-allow-modification 注册 Chat RPC 处理器
+runtime.registerRPC('echo', handler)`,
+      filename: '/project/src/server/module-chat/services/chat.ts',
+    },
+  ],
+  invalid: [],
+})
+
+// 测试6: 框架层文件不受限制
+ruleTester.run('layer-boundary - framework files', layerBoundary, {
+  valid: [
+    {
+      code: `import { runtime } from './runtime'
+runtime.registerRPC('test', handler)`,
+      filename: '/project/src/server/core/typed-runtime.ts',
+    },
+    {
+      code: `export class WSClientImpl {}`,
+      filename: '/project/src/shared/core/ws-client.ts',
+    },
+  ],
+  invalid: [],
+})
+
+console.log('✅ All layer-boundary tests passed!')

package/template/eslint-rules/__tests__/module-boundary.test.ts

@@ -0,0 +1,77 @@
+import { RuleTester } from 'eslint'
+import { moduleBoundary } from '../module-boundary'
+
+const ruleTester = new RuleTester({
+  languageOptions: {
+    ecmaVersion: 2020,
+  },
+})
+
+describe('module-boundary', () => {
+  ruleTester.run('module-boundary', moduleBoundary, {
+    valid: [
+      {
+        filename: '/project/src/client/components/Test.tsx',
+        code: `import { something } from '@shared/core'`,
+      },
+      {
+        filename: '/project/src/client/components/Test.tsx',
+        code: `import { something } from './local'`,
+      },
+      {
+        filename: '/project/src/cli/index.ts',
+        code: `import { something } from '@shared/core'`,
+      },
+      {
+        filename: '/project/src/admin/pages/Test.tsx',
+        code: `import { something } from '@shared/core'`,
+      },
+      {
+        filename: '/project/src/client/components/Test.tsx',
+        code: `import { something } from '../components/AuthButton'`,
+      },
+    ],
+    invalid: [
+      {
+        filename: '/project/src/client/components/Test.tsx',
+        code: `import { something } from '../../admin/someFile'`,
+        errors: [
+          {
+            messageId: 'directCrossModuleImport',
+            data: { fromModule: 'client', toModule: 'admin' },
+          },
+        ],
+      },
+      {
+        filename: '/project/src/client/components/Test.tsx',
+        code: `import { something } from '../../cli/someFile'`,
+        errors: [
+          {
+            messageId: 'directCrossModuleImport',
+            data: { fromModule: 'client', toModule: 'cli' },
+          },
+        ],
+      },
+      {
+        filename: '/project/src/admin/pages/Test.tsx',
+        code: `import { something } from '../../client/someFile'`,
+        errors: [
+          {
+            messageId: 'directCrossModuleImport',
+            data: { fromModule: 'admin', toModule: 'client' },
+          },
+        ],
+      },
+      {
+        filename: '/project/src/cli/index.ts',
+        code: `import { something } from '../admin/someFile'`,
+        errors: [
+          {
+            messageId: 'directCrossModuleImport',
+            data: { fromModule: 'cli', toModule: 'admin' },
+          },
+        ],
+      },
+    ],
+  })
+})

package/template/eslint-rules/__tests__/no-direct-zod-import-in-file-routes.test.ts

@@ -0,0 +1,45 @@
+import { RuleTester } from 'eslint'
+import { noDirectZodImportInFileRoutes } from '../no-direct-zod-import-in-file-routes.js'
+
+const ruleTester = new RuleTester({
+  languageOptions: {
+    ecmaVersion: 2020,
+    sourceType: 'module',
+  },
+})
+
+ruleTester.run('no-direct-zod-import-in-file-routes', noDirectZodImportInFileRoutes, {
+  valid: [
+    // 正确的导入方式 - 从 @hono/zod-openapi 导入 z
+    {
+      code: "import { z } from '@hono/zod-openapi'",
+      filename: 'src/server/module-file/routes/file-routes.ts',
+    },
+    // 其他文件不受限制
+    {
+      code: "import { z } from '@hono/zod-openapi'",
+      filename: 'src/server/other-file.ts',
+    },
+    // file-routes.ts 中从 zod 导入其他内容（非 z）是允许的
+    {
+      code: "import { ZodType } from 'zod'",
+      filename: 'src/server/module-file/routes/file-routes.ts',
+    },
+  ],
+  invalid: [
+    // 错误：直接从 zod 导入 z
+    {
+      code: "import { z } from 'zod'",
+      filename: 'src/server/module-file/routes/file-routes.ts',
+      errors: [{ messageId: 'noDirectZodImport' }],
+    },
+    // 错误：混合导入中包含 z
+    {
+      code: "import { z, ZodType } from 'zod'",
+      filename: 'src/server/module-file/routes/file-routes.ts',
+      errors: [{ messageId: 'noDirectZodImport' }],
+    },
+  ],
+})
+
+console.log('All tests passed!')