pma-bun

Bun 项目实施指南

将此技能与 /pma 配合使用。/pma 负责工作流、审批和任务跟踪；本指南定义审批后的实施基线。

保持此入口文件简短。仅加载相关参考资料包。

范围

适用于由 PMA 管理的 Bun 后端、API 服务和内部工具。与 API 一同交付的 SPA（在同一仓库中）可通过同级 web/ 目录和 pma-web 支持，无需使用 Bun workspace。

不适用于纯前端 SPA、Node 专用运行时指南或非 PMA 工作流。

加载顺序

1. 始终先加载 references/baseline.md。
2. 加载 references/runtime.md，了解引导流程、配置、根目录解析、HTTP 服务、OpenAPI 契约与文档、日志记录、PID 锁以及开发/生产环境拆分。
3. 加载 references/data-and-testing.md，了解 Drizzle、SQLite 优先存储、bun:sqlite 驱动设置、源码和编译模式下的迁移、仓库模式及测试。
4. 加载 references/delivery.md，了解编译流程、嵌入资源、CI 门禁、可观测性、Docker、安全性和 Git 工作流。

快速路由

• 新项目设置或仓库重组（单个 API / API + 同级 SPA / monorepo）→ references/baseline.md
• 依赖版本（注册表验证、固定版本规则）→ references/baseline.md Dependency Freshness
• 运行时（app.ts / index.ts / 可选的 dev.ts、配置、启动、优雅关闭、日志记录、PID 锁）→ references/runtime.md
• 路由和 API 文档（强制规则：hono-openapi、/openapi.json、/docs）→ references/runtime.md
• 开发 URL 路由（nsl）→ references/runtime.md（完整协议 → /pma references/dev-environment.md；多应用工作区设置 → /pma docs/monorepo-example.md）
• 数据访问（架构设计、SQLite 设置、迁移、仓库）→ references/data-and-testing.md
• 测试（bun:test、覆盖率阈值、OpenAPI 契约测试、编译模式冒烟测试）→ references/data-and-testing.md
• CI 和交付（编译流水线、嵌入资源、二进制交付、Docker、PR 就绪检查）→ references/delivery.md

参考资料包

• references/baseline.md 范围、布局选择（单个 API 与 monorepo，或 API + 同级 SPA）、技术栈、必需的质量门禁、脚本、约定和实施工作流。
• references/runtime.md TypeScript 默认设置、配置加载、引导结构、hono-openapi 路由和契约规则、中间件、日志记录、文档路由及运行时生命周期。
• references/data-and-testing.md 基于 SQLite 优先存储的 Drizzle、源码和编译模式下的迁移策略、仓库边界、覆盖率配置及测试规则。
• references/delivery.md 使用 --asset 嵌入资源的编译流水线、安全模式、可观测性、CI 流水线、Docker、workspace 规则及 Git 约定。

验收清单

合并前：

• lint、typecheck、build 均通过
• bun test --coverage 通过；阈值在 bunfig.toml（coverageThreshold，0.8 或更高）中设置
• 启动时使用 Zod 验证环境配置；业务逻辑中不读取 Bun.env
• 路由遵循 Routing Hard Lock；/openapi.json 与运行时验证一致，且 /docs 可打开该文档
• 后端进程中不包含 Vite（不使用 @hono/vite-dev-server，dev.ts 中也没有 Vite 中间件）
• nsl 开发路由可用（bunx nsl run -n <name>:/api -s -- bun --watch src/index.ts）；生产引导不依赖 nsl
• 已提交迁移；交付二进制文件时，通过 --asset 嵌入 drizzle/（同级 SPA 还需嵌入 web/dist），并通过编译模式冒烟测试
• 在注册表中验证新增或升级的依赖；任何非最新版本的固定依赖都附有记录在案的原因

如果仓库有意偏离这些要求，应在提案中明确说明偏差，并确保脚本、文档和 CI 中的做法一致。