chore: agentic upgrade

2026-05-17 02:12:18 +03:00
parent b8b8247ff3
commit 6e82165566
98 changed files with 9231 additions and 231 deletions
@@ -0,0 +1,41 @@
+---
+name: bun-best-practices
+description: Use when working in this repository with Bun scripts, dependency installs, tests, lockfiles, dev servers, Elysia API runtime, or frontend bundling decisions.
+---
+
+# Bun Best Practices
+
+This repo is Bun-native: Bun is the package manager, script runner, TypeScript/JSX runtime, test runner, API runtime, and frontend bundler unless a task has a specific compatibility constraint.
+
+## Project Guidance
+
+- Keep dependency declarations in `package.json`, exact resolution state in `bun.lock`, and Bun configuration in `bunfig.toml`. Do not add npm, Yarn, or pnpm lockfiles for normal work.
+- Prefer `bun run <script>` for repo scripts: `dev`, `dev:all`, `styles:build`, `web:dev`, `api:dev`, `build`, and `check`.
+- Let Bun execute `.ts`, `.tsx`, `.js`, and `.jsx` directly. Avoid `ts-node`, `tsx`, `node --loader`, or transpile-first flows unless an external tool requires them.
+- For the Elysia API, treat Bun runtime changes as production-sensitive: add smoke/load checks, watch RSS/native memory as well as JS heap, handle client disconnects for long-lived responses, keep monitoring visible, and preserve a rollback path for runtime upgrades.
+- Prefer Bun's built-in test runner for new simple TypeScript-first tests, but preserve Jest/Vitest when existing tests depend on their exact mocking, isolation, or DOM behavior.
+
+## Quick Reference
+
+| Task | Preferred command |
+| --- | --- |
+| Install/update deps | `bun install` |
+| Reproducible CI install | `bun ci` |
+| Run all dev surfaces | `bun run dev:all` |
+| Run API dev server | `bun run api:dev` |
+| Run web dev server | `bun run web:dev` |
+| Build | `bun run build` |
+| Check project | `bun run check` |
+| Run tests | `bun test` |
+| Restart on file changes | `bun --watch run <script>` |
+| Hot reload preserving global state | `bun --hot run <script>` |
+
+`bun run` resolves package scripts first, then files, package binaries, and finally system commands. If a command name is ambiguous, prefer the explicit package script.
+
+## Common Mistakes
+
+- Putting watch flags after `run`: use `bun --watch run api:dev`, not `bun run --watch api:dev`.
+- Confusing `--watch` and `--hot`: `--watch` restarts the process; `--hot` soft reloads and preserves global state.
+- Using `bun install` in CI when reproducibility matters: use `bun ci` so the lockfile is frozen.
+- Adding Node-centric shims because TypeScript is present: Bun already executes TS/JSX directly.
+- Treating runtime adoption as risk-free: Bun is excellent for tooling and dev speed, but production runtime changes still need load/smoke coverage, memory monitoring, disconnect cleanup, and rollback.