imbytecat/fullstack-starter
1
1
Fork 3
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
310 Commits 2 Branches 0 Tags
fafe02bdbdff88c4ec6140f83e14aa3732a78de2
Commit Graph

40 Commits

Author SHA1 Message Date
imbytecat fafe02bdbd refactor: 主动审计修复多处可观测性、依赖、代码质量缺口 
通过并行 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 正确序列化 ✓）
 2026-04-25 17:06:22 +08:00
imbytecat 815ee31f95 refactor(layout): 根目录脚本归位 src/ 与 scripts/，sql.d.ts 下沉到 db/ 
- bin.ts → src/bin.ts (生产入口归并到 src/，import 改用 #package + @/cli/*)
- compile.ts → scripts/compile.ts (开发期工具)
- embed-migrations.ts → scripts/embed-migrations.ts (codegen)
- src/sql.d.ts → src/server/db/sql.d.ts (与唯一消费者 migrations.gen.ts 共址)

效果：项目根从 3 个零散 .ts 减为 0 个，src/ 是完整应用源码，scripts/
明确区分开发期工具。所有 package.json scripts、AGENTS.md layout/CLI 章节、
compile.ts ENTRYPOINT 与 .js.map 清理路径同步更新。

验证：fix / typecheck / test 3/3 / build 570ms / compile 117M / docker
compose 全套（migrate 干净的 logger=cli.migrate JSON 日志、app /health
200、POST /api/todo/create 成功）。
 2026-04-25 16:50:48 +08:00
imbytecat 34d2cbb1cd refactor(logging): 二次审计修复 oracle 漏掉的可观测性缺口与占位符冗余 
二次深度审计发现：

1. shutdown.ts SIGINT/SIGTERM 路径完全沉默——生产环境 k8s pod 终止时
   操作者在日志里看不到任何痕迹。补 getLogger(['shutdown']) 三条日志：
   - "Draining for shutdown" {signal, graceMs} (优雅关停起点)
   - "Forcing exit on repeated signal" {signal} (二次信号强制退出)
   - "DB pool closed, exiting" (干净退出确认)

2. interceptors.ts 与 shutdown.ts 的 {error}/{signal} 占位符在 JSON 模式
   下导致 message 字段重复 inspect 转义 properties 里的同一份内容
   （Error/对象会被 JSON.stringify 内联进 message，引号被反斜杠转义）。
   规则收敛：占位符仅用于"想要内联渲染"的基本类型（id、count、duration），
   对象/Error 直接放 properties，message 保持人类可读短句。

3. AGENTS.md Logging 段更新示例与规则，反映实际最佳实践。

端到端验证（compose + Postgres 18-alpine）：
- /api/rpc/todo/list 成功 → logger=db level=INFO 输出 SQL ✓
- /api/rpc/todo/create 校验失败 → logger=api level=ERROR
  message="Unhandled error in ORPC handler" 干净，properties.error
  完整保留 code/status/message/data 字段 ✓
- SIGTERM → 三条 shutdown logger 事件按预期输出 ✓
- typecheck / test 3/3 / build / compile 117M 全绿 ✓
 2026-04-25 16:24:00 +08:00
imbytecat ce39faf778 refactor(logging): 接受 oracle 审计建议打磨三处不够极致的细节 
1. configureSync 用 getConfig() === null 守卫幂等初始化。原写法
   reset: true 在 ESM 缓存正常时多余、HMR 重复求值时会反复
   resetSync() + 累积 process.on('exit') 监听器。

2. ['logtape','meta'] logger 加 parentSinks: 'override'。原配置
   它既挂自己的 console sink、又继承 root sink，meta 的 warning/
   error/fatal 会被打印两次。

3. DrizzleLogger 显式传 'info' level。原默认 'debug' 与 LOG_LEVEL
   默认 'info' 形成隐形依赖：用户必须同时设两个变量才能看到 SQL。
   现在 LOG_DB=true 单开关即生效，符合"开关即可用"审美。

附带：删除未消费的 export type { LogLevel }；getLogger 改成直接
re-export from '@logtape/logtape'，少一层本地 import 间接。

端到端验证（compose + Postgres 18-alpine）：
- LOG_DB=true 默认 LOG_LEVEL=info 下 SQL 以 level=INFO logger=db 输出 ✓
- meta logger 不再重复 sink ✓
- typecheck / test 3/3 / build / compile 117M 全绿 ✓

Oracle 审计 ses_23c5090efffe1jzPR5fVVm1y6m，KISS 评分由 8/10 升至 9.2/10。
 2026-04-25 16:14:30 +08:00
imbytecat cc3a5dc5ad feat(logging): 引入 LogTape 替换 console.* 为结构化日志 
为什么选 LogTape（2026 实测）：
- pino 在 bun build --compile 编译产物里因 worker_threads + 动态 require 在
  /\$bunfs/ 虚拟文件系统中崩溃，与单二进制部署核心目标冲突；
- LogTape 零依赖（5.3KB）、零 worker、纯 ESM、原生 Bun 导出条件，runtime
  agnostic，配合 configureSync 完美兼容 --bytecode 模式（无裸 top-level await）；
- 一等公民集成：@logtape/drizzle-orm（SQL 查询日志）、@logtape/otel（后续
  OpenTelemetry sink 留扩展点）。

变更：
- src/server/logger.ts: configureSync 引导 + getLogger 重导出。format 默认
  process.stdout.isTTY ? pretty : json，可经 LOG_FORMAT 显式覆盖（绕开 Bun
  bundler 把 process.env.NODE_ENV 在 --minify 时 inline 成字面量的特殊处理）。
- src/server/api/interceptors.ts: logError 改用 getLogger(['api']).error(...) +
  结构化 properties，弃 logger.error 顶层 API。
- src/cli/migrate.ts: 所有 console.log 改走 getLogger(['cli','migrate'])，logger
  在 run() 内 lazy-import 以保持 citty subcommand 模块体 side-effect-free。
- src/server/db/index.ts: env.LOG_DB=true 时挂 DrizzleLogger 适配器，SQL 查询
  按类别 ['db'] 在 debug 级输出（含 query/params/formattedQuery 三字段）。

新增 env 旋钮（t3-oss 校验）：
- LOG_LEVEL: trace|debug|info|warning|error|fatal，默认 info
- LOG_FORMAT: pretty|json，默认 TTY 自动选
- LOG_DB: stringbool，默认 false

端到端验证（compose + Postgres 18-alpine）：
- TTY 终端：pretty 输出含 ✨ 图标 + ANSI 彩色 + 类别·路径 ✓
- 管道/Docker：JSON Lines 一行一条，含 @timestamp/level/logger/properties ✓
- LOG_FORMAT=pretty 强制覆盖 ✓
- ./server migrate 应用 migration 并经 logger 输出 ✓
- ./server serve + RPC round-trip：interceptor logError 与 drizzle SQL 日志
  在生产 JSON 模式下结构化输出 ✓
- fix / typecheck / test 3/3 / build / compile 117M 二进制全绿
 2026-04-25 16:04:31 +08:00
imbytecat d9210b3b0b chore(deps): 升级 TanStack Start 至 1.167.48，移除 start-plugin-core patch 
upstream 已修（PR #7249，1.169.4 拆分 vite/rsbuild subpath，
@rsbuild/core 列为 optional peer），patches/ 不再必要。

- @tanstack/react-start ^1.167.43 → ^1.167.48
- @tanstack/react-router ^1.168.23 → ^1.168.24
  (react-start@1.167.48 exact 依赖，避免 lockfile 双版本)
- 删除 patches/@tanstack%2Fstart-plugin-core@1.168.0.patch
- 删除 package.json patchedDependencies 块
- AGENTS.md 移除 patches/ layout 说明

验证：fix / typecheck / test / build / compile 均通过；
start-plugin-core@1.169.4 dist 不再静态 import rsbuild。
 2026-04-25 14:52:15 +08:00
imbytecat ed257fe4e6 refactor: 应用 Oracle round-4 复核，硬化 migrator 与默认安全值 
- migrate: 校验已应用 migration 的 SHA-256，拒绝 schema drift；
  split 后 trim + skip empty，避免空 statement 触发 SQL 错误
- todo.contract: update 拒绝空 patch
- env: DATABASE_URL 限定 postgres(ql):// scheme，配置错误更早失败
- compile: autoloadDotenv: false，二进制部署不再吞 cwd 的 .env
- Error.tsx: 生产环境隐藏 error.message，避免内部错误泄露
- AGENTS: 同步 generatedFieldKeys / migrator 行为新描述
 2026-04-25 14:38:44 +08:00
imbytecat f520b54ca5 docs(agents): 同步 embed-migrations 与 sql.d.ts，修陈旧描述 
- CLI 帮助块与 Layout migrate.ts 注释从 "from ./drizzle" 改为 "embedded migrations"
- 补 src/sql.d.ts（with { type: 'text' } SQL 导入的载体）到 Layout
- 补 patches/（patchedDependencies 用途）到 Layout
 2026-04-25 14:11:21 +08:00
imbytecat 7e27640a26 feat(deploy): migrations 嵌入二进制，实现真单文件部署 
- embed-migrations.ts：扫 ./drizzle/meta/_journal.json，生成 src/server/db/migrations.gen.ts，每条 SQL 通过 `import sql_<idx> from '../../../drizzle/<tag>.sql' with { type: 'text' }` 在 bun build --compile 时被静态嵌入二进制
- migrate.ts 重写：runtime 用 createHash('sha256') 计算迁移哈希，仅用 db.execute(sql) + db.transaction() 公开 API 写入 drizzle.__drizzle_migrations 簿记表（不依赖 @internal 的 db.dialect/db.session）
- db:generate 链 db:embed，保证 SQL 改动总是同步到 migrations.gen.ts
- Dockerfile 删 COPY drizzle/，binary 是部署唯一 artifact
- 同步 README / AGENTS / biome.json
 2026-04-25 14:05:58 +08:00
imbytecat e28fe9dc7b perf(compile): 启用 bytecode + minify + inline sourcemap 
- Bun 官方 bytecode caching：中型应用 startup ~2x（docs.bun.sh/docs/bundler/bytecode）
- minify：减小 bytecode 体积，二进制仅 +2MB sourcemap
- sourcemap inline：嵌入二进制，保证错误堆栈可读，并在 compile.ts 清理 bundler 残留的 *.js.map
 2026-04-25 14:05:35 +08:00
imbytecat a3a62c24b9 docs: 新增 README，AGENTS 同步至当前架构 
- README: 用户向 quick-start、scripts 表、add-a-feature checklist、deploy 流程
- AGENTS:
  - 修订 stale 文案（VITE_APP_TITLE/experimental_defaults/.gitkeep/route 组件风格）
  - 新增 Testing 段（bun test 约定）和 Endpoints 段（/, /health, /api/*）
  - Layout 补 logger.ts、health.ts、components/、styles.css、根 drizzle/
  - 追加 10 条 room-to-grow 纪律（client query / middleware / interceptor / 测试等扩展边界）
 2026-04-25 13:31:45 +08:00
imbytecat 5dd54ec9e9 docs(agents): 同步架构简化后的规约 
- DB：module-level const db（删掉 getDB/closeDB 的描述），说明为什么
  不需要兼容 Cloudflare Workers 的 lazy init
- Routers 直接 import db，不再过 middleware；只在真正需要 per-request
  上下文时才新建 middlewares/
- Layout 刷新 db/ 与 api/ 目录的注释；Don'ts 补上不要回退到 lazy DB 单例
 2026-04-24 20:38:51 +08:00
imbytecat 19e60d358f feat(cli): 引入 citty CLI，迁移改为显式 ./server migrate 
- 顶层新增 bin.ts 作为编译入口，citty 懒加载 src/cli/ 下子命令
- src/cli/serve.ts 通过 _serve-nitro.mjs 桥接启动 Nitro（规避
  .output/server/index.mjs 顶层 serve(...) 的副作用导入）
- src/cli/migrate.ts 显式跑 drizzle migrate；env / drizzle 都在 run()
  里 await import，避免 citty --help 遍历 subCommands 时触发 env 校验
- compile.ts 入口切到 bin.ts；移除 src/server/plugins/migrate.ts
  与 vite.config.ts 中的启动时自动迁移
- compose.yaml 新增一次性 migrate 服务，app depends_on
  service_completed_successfully，保证迁移先行再起服
- tsconfig 排除 .output / out；AGENTS.md 补充 CLI 与部署规约
 2026-04-24 20:32:32 +08:00
imbytecat 4518a63959 docs(agents): 同步 drizzle 0.x 降级后的指引 
修正 AGENTS.md 里与 1.0 beta 相关的过时条目（drizzle-orm/zod、
defineRelations、RQB v2 对象语法等），改为记录当前真实用法：
drizzle-zod 包、`drizzle({ schema })`、RQB v1 回调写法。顺手裁掉
通用的 Biome/TS 说明，补上几条仓库特有的坑（Nitro 插件在 vite.config
里注册、distroless cc 变体、无 CI/pre-commit 等）。
 2026-04-24 20:13:56 +08:00
imbytecat 77b3484415 refactor: 改用 Nitro 插件实现启动时数据库迁移 2026-04-02 03:42:45 +08:00
imbytecat ed770909ef chore: 添加 Docker 打包和 Compose 编排支持 2026-04-02 02:43:21 +08:00
imbytecat 7700ba4520 docs: 修正 AGENTS.md 与代码库的 12 处不一致 2026-04-02 00:37:44 +08:00
imbytecat 22363279c8 docs: 精简 AGENTS.md 文档结构并优化内容呈现 2026-04-01 23:24:23 +08:00
imbytecat cd7b65fda4 refactor: flatten monorepo into standalone project 2026-04-01 19:43:21 +08:00
imbytecat 036afb8d20 chore: remove React Compiler and @rolldown/plugin-babel 2026-04-01 18:26:09 +08:00
imbytecat cd7448c3b3 docs: 统一使用 bun run <script> 避免与 Bun 内置子命令冲突 
bun build 会调用 Bun 内置 bundler 而非 package.json script，
将所有文档中的 bun <script> 改为 bun run <script> 以避免歧义。
bun test 保留不变（直接使用 Bun 内置 test runner）。
 2026-03-05 12:57:26 +08:00
imbytecat 58620b4d4b feat: 补充 root compile/dist 脚本，通过 Turbo filter 委托到对应 app 2026-03-05 11:56:49 +08:00
imbytecat 04b8dedb3e fix: 修正 middleware 导入路径、清理 catalog 冗余项、同步文档 2026-03-05 11:22:49 +08:00
imbytecat 02bdfffe79 refactor(client): 合并 orpc.ts 和 query-client.ts 为单文件，遵循 ORPC 官方模式 2026-03-05 11:05:53 +08:00
imbytecat 0cd8b57d24 refactor: 优化项目结构 — 修复拼写、提取共享 interceptor、扁平化 db 目录、清理空包 2026-03-05 10:58:55 +08:00
imbytecat 0438b52c93 refactor(db): 移除 drizzle() 多余的 schema 参数，RQBv2 只需 relations 2026-03-05 10:37:47 +08:00
imbytecat fd9478d64e docs: 同步 AGENTS.md 至 Drizzle v1 beta 并添加开发原则 
- 所有 AGENTS.md 新增「开发原则」：不向后兼容、改代码必须同步文档、前向迁移
- 根 AGENTS.md: 更新 Database 段落为 Drizzle v1 beta + postgres-js + RQBv2
- server AGENTS.md: 更新 tech stack、目录结构、ORPC 示例、数据库段落
  - drizzle-zod → drizzle-orm/zod
  - bun-sql → postgres-js
  - RQBv1 回调 → RQBv2 对象语法
  - 新增 relations.ts 和 DB instance 示例
- desktop AGENTS.md: 添加开发原则和文档同步规则
 2026-03-05 10:21:31 +08:00
imbytecat 94a9122f34 feat(build): 统一编译命令并默认启用双架构 2026-02-15 23:48:37 +08:00
imbytecat 275c8e4795 docs(agents): 同步多架构构建与打包命令说明 2026-02-15 23:32:32 +08:00
imbytecat e171db8196 refactor: simplify compile.ts to single-target and add per-platform compile scripts 
- Rewrite compile.ts from 112 to 66 lines: single target with auto-detect host, remove multi-target batch logic
- Add compile:linux/mac/win scripts to server, root, and turbo configs
- Wire desktop dist:* to depend on matching server compile:* (avoid unnecessary cross-platform compilation)
- Update AGENTS.md docs across root, server, and desktop
 2026-02-08 22:25:30 +08:00
imbytecat dac6bb1643 refactor: 统一打包命令为 dist 体系，build 仅编译不打包 
- build:linux/mac/win → dist/dist:linux/dist:mac/dist:win
- Turbo 任务依赖：desktop#dist:* → server#compile → server#build
- 根目录 bun dist 一条命令完成完整打包流水线
- 更新 AGENTS.md 文档同步命令变更
 2026-02-08 20:48:58 +08:00
imbytecat 7318600e20 refactor(desktop): 替换 WebUI 为 Electron + electron-vite 桌面壳方案 
- 使用 electron-vite 构建 main/preload，electron-builder 打包分发
- main process: dev 模式直连 localhost:3000，生产模式 spawn sidecar binary
- 添加 loading 页面，server 就绪前显示加载动画
- 更新 catalog 依赖: electron, electron-vite, electron-builder
- 移除 @webui-dev/bun-webui 依赖
 2026-02-08 18:16:13 +08:00
imbytecat 41e79449ce docs: 更新 AGENTS.md 适配 Electrobun 替代 Tauri 2026-02-07 17:00:52 +08:00
imbytecat adb14cff77 chore: 重构 Turbo 构建配置并强化 Bun 专用说明 
将应用特定的构建输出配置下沉至各自 turbo.json，根级 build 任务添加拓扑依赖；AGENTS.md 统一添加 Bun 专用运行时警告；桌面端启用 Linux CEF 渲染器。
 2026-02-07 16:14:55 +08:00
imbytecat e41c4e4515 docs: 更新 AGENTS.md 文档结构和内容 
- 新增根目录 AGENTS.md 作为 monorepo 总览
- 移动 desktop AGENTS.md 从 src-tauri/ 到 apps/desktop/
- 修正 server AGENTS.md 目录结构 (src/server/api/ 而非 src/orpc/)
- 明确 desktop 为纯 Tauri 壳子，无前端代码，通过 sidecar 加载 server
 2026-02-07 03:29:51 +08:00
imbytecat 896bb0ca7d refactor: 重命名 AGENTS.md 文件至 server 目录 
- 重命名 AGENTS.md 文件至 apps/server/ 目录下
 2026-01-21 21:46:20 +08:00
imbytecat 4b69095a8d docs: 更新项目文档，优化中文描述与格式化 
- 更新项目文档以反映最新的开发规范、命令和目录结构，优化中文描述并统一格式化。
 2026-01-18 17:24:40 +08:00
imbytecat 2acf387ffd feat: 添加桌面端壳层选项Tauri v2并指向桌面特定指南 
- 添加桌面端壳层选项Tauri v2并指向桌面特定指南
 2026-01-18 17:20:16 +08:00
imbytecat 03c6b84a39 feat: 添加 ORPC 类型安全 RPC 层集成指南 
- 添加 ORPC 类型安全 RPC 层的完整集成指南，包括合约定义、处理器实现、路由注册及在组件中使用的方法。
 2026-01-18 03:51:48 +08:00
imbytecat e5bcf44bc6 docs: 添加AI编码代理指南并清理废弃脚本 
- 创建AI编码代理指南文档，明确项目技术栈、代码规范、文件结构及开发流程。
- 移除已废弃的 serve 脚本，保持脚本列表简洁有效。
 2026-01-17 03:01:45 +08:00