From fafe02bdbdff88c4ec6140f83e14aa3732a78de2 Mon Sep 17 00:00:00 2001
From: imbytecat <imbytecat@gmail.com>
Date: Sat, 25 Apr 2026 17:06:22 +0800
Subject: [PATCH] =?UTF-8?q?refactor:=20=E4=B8=BB=E5=8A=A8=E5=AE=A1?=
 =?UTF-8?q?=E8=AE=A1=E4=BF=AE=E5=A4=8D=E5=A4=9A=E5=A4=84=E5=8F=AF=E8=A7=82?=
 =?UTF-8?q?=E6=B5=8B=E6=80=A7=E3=80=81=E4=BE=9D=E8=B5=96=E3=80=81=E4=BB=A3?=
 =?UTF-8?q?=E7=A0=81=E8=B4=A8=E9=87=8F=E7=BC=BA=E5=8F=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

通过并行 explore + librarian + 自查发现并修复：

代码缺陷
- shutdown.ts: db.$client.end().finally(...) 静默吞错——关闭失败会
  谎报 "DB pool closed" 后照常 exit 0。改用 await + try/catch
  分别记录成功/失败，setTimeout 也换成 Bun.sleep。
- interceptors.ts: 两条 instanceof ORPCError && instanceof
  ValidationError 重复检查，改用 early return + 单 if 分支区分 code。
- types.ts: 移除从未被引用的 RouterInputs 死代码（仅 RouterOutputs
  被 TodoItem 用到）。

Bun 原生 API（删/换 Node 兼容层）
- fields.ts: uuid v7 → Bun.randomUUIDv7()，删除 uuid 依赖
- migrate.ts: node:crypto.createHash → Bun.CryptoHasher.hash，
  少一个 Promise.all 项 + 一个 import
- shutdown.ts: setTimeout → Bun.sleep（顺带）

Biome 2.4 规则补强
- domains.types: "all"——开启类型感知规则集（noFloatingPromises /
  noMisusedPromises / useAwaitThenable / noUnnecessaryConditions
  等 Promise/异步陷阱）
- domains.drizzle: "recommended"、domains.react: "recommended"
- 显式开启 suspicious.noImportCycles（2.4 已 promote）

文档
- AGENTS.md 在 Stack & runtime 段加 "Prefer Bun-native APIs"
  原则，列出 UUIDv7/SHA-256/sleep/Bun.file 的优先路径
- AGENTS.md 在 Code style (Biome) 段记录本次启用的 lint domain
  与 noImportCycles 规则

验证：fix / typecheck / test 3/3 / build 568ms / compile 117M /
docker compose 全套（migrate JSON 日志 ✓、UUIDv7 写入 ✓、SIGTERM
shutdown 正确序列化 ✓）
---
 AGENTS.md                      |  2 ++
 biome.json                     |  6 ++++++
 bun.lock                       |  3 ---
 package.json                   |  1 -
 src/cli/migrate.ts             |  5 ++---
 src/server/api/interceptors.ts |  6 ++++--
 src/server/api/types.ts        |  3 +--
 src/server/db/fields.ts        |  3 +--
 src/server/plugins/shutdown.ts | 20 +++++++++++---------
 9 files changed, 27 insertions(+), 22 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 5d061a4..c0193cc 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -5,6 +5,7 @@ Compact, repo-specific notes for AI agents. Generic language/framework knowledge
 ## Stack & runtime
 
 - **Bun-only** (`mise.toml` pins `bun = 1.3.13`). Never invoke `npm`/`npx`/`node`/`yarn`/`pnpm`. Use `bun run <script>` (bare `bun <script>` can collide with Bun built-in subcommands).
+- **Prefer Bun-native APIs over external packages and `node:*` polyfills.** UUIDv7 → `Bun.randomUUIDv7()` (not the `uuid` package); SHA-256 → `Bun.CryptoHasher.hash('sha256', s, 'hex')` (not `node:crypto.createHash`); short sleeps → `Bun.sleep(ms)` (not raw `setTimeout` with promise wrapping); file I/O in build scripts → `Bun.file` / `Bun.write` are fine. The runtime is Bun, the deployment target is Bun, the test runner is Bun — there is no "portability" concern that would justify dragging in npm packages or Node compat shims for things Bun ships natively.
 - TanStack Start (React 19 SSR, file-routed) + Vite 8 + Nitro (nightly, preset `bun`). Vite dev port is **strict 3000**.
 - PostgreSQL + **Drizzle ORM `0.45.2` (0.x, NOT 1.0 beta)** — see "Drizzle" section, this matters a lot.
 - ORPC (contract-first), TanStack Query v5, Tailwind v4.
@@ -97,6 +98,7 @@ Contract → Router → Handler → Client, all type-safe from a single contract
 ## Code style (Biome)
 
 - 2-space, LF, single quotes, **semicolons as-needed** (omitted unless required), 120-col, arrow parens always, `useArrowFunction: "error"` (covers function *expressions* only). Also `noReactPropAssignments: "error"`.
+- Lint domains enabled (Biome 2.4): `types: "all"` (catches `noFloatingPromises`, `noMisusedPromises`, `useAwaitThenable`, `noUnnecessaryConditions` — TS-aware async/promise traps), `drizzle: "recommended"`, `react: "recommended"`. `noImportCycles` is on under `suspicious`.
 - **Route components use `function Foo()` declarations**, placed below the `Route` config so the file reads top-down (route on top, component below). This is the official TanStack Router/Start pattern and relies on hoisting — `const Foo = () => {}` would TDZ-error when referenced from `createFileRoute({ component: Foo })` above it. Inline arrows are fine for trivial leaf components (e.g. plain redirect routes). Non-route components (UI primitives in `src/components/`) use `const Foo = () => {}`.
 - Imports are auto-organized into two groups (external, then `@/*`), each alphabetical, with `import type` interleaved (NOT a separate group). `bun run fix` handles this; don't hand-sort.
 - Files: utils `kebab-case.ts`, components `PascalCase.tsx`.
diff --git a/biome.json b/biome.json
index 1292631..3990b74 100644
--- a/biome.json
+++ b/biome.json
@@ -17,6 +17,11 @@
   },
   "linter": {
     "enabled": true,
+    "domains": {
+      "drizzle": "recommended",
+      "react": "recommended",
+      "types": "all"
+    },
     "rules": {
       "recommended": true,
       "complexity": {
@@ -30,6 +35,7 @@
       },
       "suspicious": {
         "noExplicitAny": "error",
+        "noImportCycles": "error",
         "noTsIgnore": "error"
       }
     }
diff --git a/bun.lock b/bun.lock
index 7ae5741..19376c7 100644
--- a/bun.lock
+++ b/bun.lock
@@ -25,7 +25,6 @@
         "postgres": "^3.4.9",
         "react": "^19.2.5",
         "react-dom": "^19.2.5",
-        "uuid": "^14.0.0",
         "zod": "^4.3.6",
       },
       "devDependencies": {
@@ -666,8 +665,6 @@
 
     "use-sync-external-store": ["use-sync-external-store@1.6.0", "", { "peerDependencies": { "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0" } }, "sha512-Pp6GSwGP/NrPIrxVFAIkOQeyw8lFenOHijQWkUTrDvrF4ALqylP2C/KCkeS9dpUM3KvYRQhna5vt7IL95+ZQ9w=="],
 
-    "uuid": ["uuid@14.0.0", "", { "bin": { "uuid": "dist-node/bin/uuid" } }, "sha512-Qo+uWgilfSmAhXCMav1uYFynlQO7fMFiMVZsQqZRMIXp0O7rR7qjkj+cPvBHLgBqi960QCoo/PH2/6ZtVqKvrg=="],
-
     "vite": ["vite@8.0.10", "", { "dependencies": { "lightningcss": "^1.32.0", "picomatch": "^4.0.4", "postcss": "^8.5.10", "rolldown": "1.0.0-rc.17", "tinyglobby": "^0.2.16" }, "optionalDependencies": { "fsevents": "~2.3.3" }, "peerDependencies": { "@types/node": "^20.19.0 || >=22.12.0", "@vitejs/devtools": "^0.1.0", "esbuild": "^0.27.0 || ^0.28.0", "jiti": ">=1.21.0", "less": "^4.0.0", "sass": "^1.70.0", "sass-embedded": "^1.70.0", "stylus": ">=0.54.8", "sugarss": "^5.0.0", "terser": "^5.16.0", "tsx": "^4.8.1", "yaml": "^2.4.2" }, "optionalPeers": ["@types/node", "@vitejs/devtools", "esbuild", "jiti", "less", "sass", "sass-embedded", "stylus", "sugarss", "terser", "tsx", "yaml"], "bin": { "vite": "bin/vite.js" } }, "sha512-rZuUu9j6J5uotLDs+cAA4O5H4K1SfPliUlQwqa6YEwSrWDZzP4rhm00oJR5snMewjxF5V/K3D4kctsUTsIU9Mw=="],
 
     "vitefu": ["vitefu@1.1.3", "", { "peerDependencies": { "vite": "^3.0.0 || ^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0" }, "optionalPeers": ["vite"] }, "sha512-ub4okH7Z5KLjb6hDyjqrGXqWtWvoYdU3IGm/NorpgHncKoLTCfRIbvlhBm7r0YstIaQRYlp4yEbFqDcKSzXSSg=="],
diff --git a/package.json b/package.json
index 2aea2f9..7ad3909 100644
--- a/package.json
+++ b/package.json
@@ -51,7 +51,6 @@
     "postgres": "^3.4.9",
     "react": "^19.2.5",
     "react-dom": "^19.2.5",
-    "uuid": "^14.0.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {
diff --git a/src/cli/migrate.ts b/src/cli/migrate.ts
index 039df7c..d244a32 100644
--- a/src/cli/migrate.ts
+++ b/src/cli/migrate.ts
@@ -6,12 +6,11 @@ export default defineCommand({
     description: 'Apply pending database migrations',
   },
   async run() {
-    const [{ env }, { drizzle }, { sql }, { embeddedMigrations }, { createHash }, { getLogger }] = await Promise.all([
+    const [{ env }, { drizzle }, { sql }, { embeddedMigrations }, { getLogger }] = await Promise.all([
       import('@/env'),
       import('drizzle-orm/postgres-js'),
       import('drizzle-orm'),
       import('@/server/db/migrations.gen'),
-      import('node:crypto'),
       import('@/server/logger'),
     ])
 
@@ -22,7 +21,7 @@ export default defineCommand({
       return
     }
 
-    const sha256 = (s: string) => createHash('sha256').update(s).digest('hex')
+    const sha256 = (s: string) => Bun.CryptoHasher.hash('sha256', s, 'hex')
 
     const db = drizzle({ connection: { url: env.DATABASE_URL, max: 1, onnotice: () => {} } })
     try {
diff --git a/src/server/api/interceptors.ts b/src/server/api/interceptors.ts
index cfbbd8c..ab18a63 100644
--- a/src/server/api/interceptors.ts
+++ b/src/server/api/interceptors.ts
@@ -9,7 +9,9 @@ export const logError = (error: unknown) => {
 }
 
 export const handleValidationError = (error: unknown) => {
-  if (error instanceof ORPCError && error.code === 'BAD_REQUEST' && error.cause instanceof ValidationError) {
+  if (!(error instanceof ORPCError) || !(error.cause instanceof ValidationError)) return
+
+  if (error.code === 'BAD_REQUEST') {
     // ORPC widens issues to the Standard Schema shape; every contract here is built from Zod/drizzle-zod,
     // so the runtime objects are Zod issues. Rehydrate to reuse z.prettifyError / z.flattenError.
     const zodError = new z.ZodError(error.cause.issues as z.core.$ZodIssue[])
@@ -22,7 +24,7 @@ export const handleValidationError = (error: unknown) => {
     })
   }
 
-  if (error instanceof ORPCError && error.code === 'INTERNAL_SERVER_ERROR' && error.cause instanceof ValidationError) {
+  if (error.code === 'INTERNAL_SERVER_ERROR') {
     throw new ORPCError('OUTPUT_VALIDATION_FAILED', {
       cause: error.cause,
     })
diff --git a/src/server/api/types.ts b/src/server/api/types.ts
index f4447bb..5a617cb 100644
--- a/src/server/api/types.ts
+++ b/src/server/api/types.ts
@@ -1,6 +1,5 @@
-import type { ContractRouterClient, InferContractRouterInputs, InferContractRouterOutputs } from '@orpc/contract'
+import type { ContractRouterClient, InferContractRouterOutputs } from '@orpc/contract'
 import type { Contract } from './contracts'
 
 export type RouterClient = ContractRouterClient<Contract>
-export type RouterInputs = InferContractRouterInputs<Contract>
 export type RouterOutputs = InferContractRouterOutputs<Contract>
diff --git a/src/server/db/fields.ts b/src/server/db/fields.ts
index e02b497..edf0a47 100644
--- a/src/server/db/fields.ts
+++ b/src/server/db/fields.ts
@@ -1,10 +1,9 @@
 import { timestamp, uuid } from 'drizzle-orm/pg-core'
-import { v7 as uuidv7 } from 'uuid'
 
 export const generatedFields = {
   id: uuid('id')
     .primaryKey()
-    .$defaultFn(() => uuidv7()),
+    .$defaultFn(() => Bun.randomUUIDv7()),
   createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
   updatedAt: timestamp('updated_at', { withTimezone: true })
     .notNull()
diff --git a/src/server/plugins/shutdown.ts b/src/server/plugins/shutdown.ts
index 097ed79..8742f75 100644
--- a/src/server/plugins/shutdown.ts
+++ b/src/server/plugins/shutdown.ts
@@ -7,7 +7,7 @@ export default () => {
   const logger = getLogger(['shutdown'])
   let exiting = false
 
-  const shutdown = (signal: NodeJS.Signals) => {
+  const shutdown = async (signal: NodeJS.Signals) => {
     if (exiting) {
       logger.warn('Forcing exit on repeated signal', { signal })
       process.exit(0)
@@ -15,14 +15,16 @@ export default () => {
     exiting = true
     logger.info('Draining for shutdown', { signal, graceMs: 500 })
 
-    setTimeout(() => {
-      db.$client.end().finally(() => {
-        logger.info('DB pool closed, exiting')
-        process.exit(0)
-      })
-    }, 500)
+    await Bun.sleep(500)
+    try {
+      await db.$client.end()
+      logger.info('DB pool closed, exiting')
+    } catch (error) {
+      logger.error('DB pool close failed during shutdown', { error })
+    }
+    process.exit(0)
   }
 
-  process.on('SIGINT', () => shutdown('SIGINT'))
-  process.on('SIGTERM', () => shutdown('SIGTERM'))
+  process.on('SIGINT', () => void shutdown('SIGINT'))
+  process.on('SIGTERM', () => void shutdown('SIGTERM'))
 }