pma-bun

Bun プロジェクト実装ガイド

このスキルは /pma と併用してください。/pma がワークフロー、承認、タスク追跡を管理し、このガイドでは承認後の実装基準を定めます。

このエントリーファイルは小さく保ってください。関連するリファレンスパックのみを読み込みます。

対象範囲

PMA が管理する Bun バックエンド、API サービス、内部ツール向けです。API と同じリポジトリに含まれる SPA は、兄弟ディレクトリの web/ と pma-web を使用してサポートされます。Bun ワークスペースは必要ありません。

フロントエンドのみの SPA、Node 固有のランタイムガイド、PMA を使用しないワークフローは対象外です。

読み込み順序

1. 必ず最初に references/baseline.md を読み込みます。
2. ブートストラップの流れ、設定、ルート解決、HTTP サーバー、OpenAPI コントラクトとドキュメント、ロギング、PID ロック、開発環境と本番環境の分離については、references/runtime.md を読み込みます。
3. Drizzle、SQLite を優先するストレージ、bun:sqlite ドライバーの設定、ソースモードとコンパイルモードでのマイグレーション、リポジトリのパターン、テストについては、references/data-and-testing.md を読み込みます。
4. コンパイルの流れ、埋め込みアセット、CI ゲート、可観測性、Docker、セキュリティ、Git ワークフローについては、references/delivery.md を読み込みます。

クイックルーティング

• 新規プロジェクトのセットアップまたはリポジトリの再構成（単一 API／API と兄弟 SPA／モノレポ）→ 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／モノレポ／API と兄弟 SPA）、技術スタック、必須の品質ゲート、スクリプト、規約、実装ワークフロー。
• references/runtime.md TypeScript のデフォルト、設定の読み込み、ブートストラップ構成、hono-openapi のルートとコントラクトのルール、ミドルウェア、ロギング、ドキュメントのルート、ランタイムのライフサイクル。
• references/data-and-testing.md SQLite を優先するストレージでの Drizzle、ソースモードとコンパイルモードのマイグレーション戦略、リポジトリの境界、カバレッジの設定、テストのルール。
• references/delivery.md --asset を使ったコンパイルパイプライン、セキュリティパターン、可観測性、CI パイプライン、Docker、ワークスペースのルール、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 全体で一貫させてください。