From cd7448c3b3ae6d4f5eae785a96c4a2e6f969b093 Mon Sep 17 00:00:00 2001
From: imbytecat <imbytecat@gmail.com>
Date: Thu, 5 Mar 2026 12:57:26 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E7=BB=9F=E4=B8=80=E4=BD=BF=E7=94=A8=20?=
 =?UTF-8?q?bun=20run=20<script>=20=E9=81=BF=E5=85=8D=E4=B8=8E=20Bun=20?=
 =?UTF-8?q?=E5=86=85=E7=BD=AE=E5=AD=90=E5=91=BD=E4=BB=A4=E5=86=B2=E7=AA=81?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

bun build 会调用 Bun 内置 bundler 而非 package.json script，
将所有文档中的 bun <script> 改为 bun run <script> 以避免歧义。
bun test 保留不变（直接使用 Bun 内置 test runner）。
---
 AGENTS.md              | 92 +++++++++++++++++++++---------------------
 apps/desktop/AGENTS.md | 36 ++++++++---------
 apps/server/AGENTS.md  | 42 +++++++++----------
 turbo.json             |  7 +---
 4 files changed, 86 insertions(+), 91 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 3024e8a..f76aafc 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -4,7 +4,7 @@ Guidelines for AI agents working in this Bun monorepo.
 
 ## Project Overview
 
-> **This project uses [Bun](https://bun.sh) exclusively as both the JavaScript runtime and package manager. Do NOT use Node.js / npm / yarn / pnpm. All commands start with `bun` — use `bun install` for dependencies and `bun run` / `bun <script>` for scripts. Never use `npm`, `npx`, or `node`.**
+> **This project uses [Bun](https://bun.sh) exclusively as both the JavaScript runtime and package manager. Do NOT use Node.js / npm / yarn / pnpm. All commands start with `bun` — use `bun install` for dependencies and `bun run <script>` for scripts. Always prefer `bun run <script>` over `bun <script>` to avoid conflicts with Bun built-in subcommands (e.g. `bun build` invokes Bun's bundler, NOT your package.json script). Never use `npm`, `npx`, or `node`.**
 
 - **Monorepo**: Bun workspaces + Turborepo orchestration
 - **Runtime**: Bun (see `mise.toml` for version) — **NOT Node.js**
@@ -18,57 +18,57 @@ Guidelines for AI agents working in this Bun monorepo.
 
 ### Root Commands (via Turbo)
 ```bash
-bun dev              # Start all apps in dev mode
-bun build            # Build all apps
-bun compile          # Compile server to standalone binary (current platform)
-bun compile:darwin   # Compile server for macOS (arm64 + x64)
-bun compile:linux    # Compile server for Linux (x64 + arm64)
-bun compile:windows  # Compile server for Windows x64
-bun dist             # Package desktop distributable (current platform)
-bun dist:linux       # Package desktop for Linux (x64 + arm64)
-bun dist:mac         # Package desktop for macOS (arm64 + x64)
-bun dist:win         # Package desktop for Windows x64
-bun fix              # Lint + format (Biome auto-fix)
-bun typecheck        # TypeScript check across monorepo
+bun run dev              # Start all apps in dev mode
+bun run build            # Build all apps
+bun run compile          # Compile server to standalone binary (current platform)
+bun run compile:darwin   # Compile server for macOS (arm64 + x64)
+bun run compile:linux    # Compile server for Linux (x64 + arm64)
+bun run compile:windows  # Compile server for Windows x64
+bun run dist             # Package desktop distributable (current platform)
+bun run dist:linux       # Package desktop for Linux (x64 + arm64)
+bun run dist:mac         # Package desktop for macOS (arm64 + x64)
+bun run dist:win         # Package desktop for Windows x64
+bun run fix              # Lint + format (Biome auto-fix)
+bun run typecheck        # TypeScript check across monorepo
 ```
 
 ### Server App (`apps/server`)
 ```bash
-bun dev                   # Vite dev server (localhost:3000)
-bun build                 # Production build -> .output/
-bun compile               # Compile to standalone binary (current platform)
-bun compile:darwin        # Compile for macOS (arm64 + x64)
-bun compile:darwin:arm64  # Compile for macOS arm64
-bun compile:darwin:x64    # Compile for macOS x64
-bun compile:linux         # Compile for Linux (x64 + arm64)
-bun compile:linux:arm64   # Compile for Linux arm64
-bun compile:linux:x64     # Compile for Linux x64
-bun compile:windows       # Compile for Windows (default: x64)
-bun compile:windows:x64   # Compile for Windows x64
-bun fix                   # Biome auto-fix
-bun typecheck             # TypeScript check
+bun run dev                   # Vite dev server (localhost:3000)
+bun run build                 # Production build -> .output/
+bun run compile               # Compile to standalone binary (current platform)
+bun run compile:darwin        # Compile for macOS (arm64 + x64)
+bun run compile:darwin:arm64  # Compile for macOS arm64
+bun run compile:darwin:x64    # Compile for macOS x64
+bun run compile:linux         # Compile for Linux (x64 + arm64)
+bun run compile:linux:arm64   # Compile for Linux arm64
+bun run compile:linux:x64     # Compile for Linux x64
+bun run compile:windows       # Compile for Windows (default: x64)
+bun run compile:windows:x64   # Compile for Windows x64
+bun run fix                   # Biome auto-fix
+bun run typecheck             # TypeScript check
 
 # Database (Drizzle)
-bun db:generate           # Generate migrations from schema
-bun db:migrate            # Run migrations
-bun db:push               # Push schema (dev only)
-bun db:studio             # Open Drizzle Studio
+bun run db:generate           # Generate migrations from schema
+bun run db:migrate            # Run migrations
+bun run db:push               # Push schema (dev only)
+bun run db:studio             # Open Drizzle Studio
 ```
 
 ### Desktop App (`apps/desktop`)
 ```bash
-bun dev                   # electron-vite dev mode (requires server dev running)
-bun build                 # electron-vite build (main + preload)
-bun dist                  # Build + package for current platform
-bun dist:linux            # Build + package for Linux (x64 + arm64)
-bun dist:linux:x64        # Build + package for Linux x64
-bun dist:linux:arm64      # Build + package for Linux arm64
-bun dist:mac              # Build + package for macOS (arm64 + x64)
-bun dist:mac:arm64        # Build + package for macOS arm64
-bun dist:mac:x64          # Build + package for macOS x64
-bun dist:win              # Build + package for Windows x64
-bun fix                   # Biome auto-fix
-bun typecheck             # TypeScript check
+bun run dev                   # electron-vite dev mode (requires server dev running)
+bun run build                 # electron-vite build (main + preload)
+bun run dist                  # Build + package for current platform
+bun run dist:linux            # Build + package for Linux (x64 + arm64)
+bun run dist:linux:x64        # Build + package for Linux x64
+bun run dist:linux:arm64      # Build + package for Linux arm64
+bun run dist:mac              # Build + package for macOS (arm64 + x64)
+bun run dist:mac:arm64        # Build + package for macOS arm64
+bun run dist:mac:x64          # Build + package for macOS x64
+bun run dist:win              # Build + package for Windows x64
+bun run fix                   # Biome auto-fix
+bun run typecheck             # TypeScript check
 ```
 
 ### Testing
@@ -160,7 +160,7 @@ export const myTable = pgTable('my_table', {
 ## Critical Rules
 
 **DO:**
-- Run `bun fix` before committing
+- Run `bun run fix` before committing
 - Use `@/*` path aliases (not relative imports)
 - Include `createdAt`/`updatedAt` on all tables
 - Use `catalog:` for dependency versions
@@ -178,9 +178,9 @@ export const myTable = pgTable('my_table', {
 ## Git Workflow
 
 1. Make changes following style guide
-2. `bun fix` - auto-format and lint
-3. `bun typecheck` - verify types
-4. `bun dev` - test locally
+2. `bun run fix` - auto-format and lint
+3. `bun run typecheck` - verify types
+4. `bun run dev` - test locally
 5. Commit with descriptive message
 
 ## Directory Structure
diff --git a/apps/desktop/AGENTS.md b/apps/desktop/AGENTS.md
index 1384aa7..7e00c70 100644
--- a/apps/desktop/AGENTS.md
+++ b/apps/desktop/AGENTS.md
@@ -4,7 +4,7 @@ Thin Electron shell hosting the fullstack server app.
 
 ## Tech Stack
 
-> **⚠️ This project uses Bun as the package manager. Runtime is Electron (Node.js). Never use `npm`, `npx`, `yarn`, or `pnpm`.**
+> **⚠️ This project uses Bun as the package manager. Runtime is Electron (Node.js). Always use `bun run <script>` (not `bun <script>`) to avoid conflicts with Bun built-in subcommands. Never use `npm`, `npx`, `yarn`, or `pnpm`.**
 
 - **Type**: Electron desktop shell
 - **Design**: Server-driven desktop (thin native window hosting web app)
@@ -22,18 +22,18 @@ Thin Electron shell hosting the fullstack server app.
 ## Commands
 
 ```bash
-bun dev                    # electron-vite dev (requires server dev running)
-bun build                  # electron-vite build (main + preload)
-bun dist                   # Build + package for current platform
-bun dist:linux             # Build + package for Linux (x64 + arm64)
-bun dist:linux:x64         # Build + package for Linux x64
-bun dist:linux:arm64       # Build + package for Linux arm64
-bun dist:mac               # Build + package for macOS (arm64 + x64)
-bun dist:mac:arm64         # Build + package for macOS arm64
-bun dist:mac:x64           # Build + package for macOS x64
-bun dist:win               # Build + package for Windows x64
-bun fix                    # Biome auto-fix
-bun typecheck              # TypeScript check
+bun run dev                    # electron-vite dev (requires server dev running)
+bun run build                  # electron-vite build (main + preload)
+bun run dist                   # Build + package for current platform
+bun run dist:linux             # Build + package for Linux (x64 + arm64)
+bun run dist:linux:x64         # Build + package for Linux x64
+bun run dist:linux:arm64       # Build + package for Linux arm64
+bun run dist:mac               # Build + package for macOS (arm64 + x64)
+bun run dist:mac:arm64         # Build + package for macOS arm64
+bun run dist:mac:x64           # Build + package for macOS x64
+bun run dist:win               # Build + package for Windows x64
+bun run fix                    # Biome auto-fix
+bun run typecheck              # TypeScript check
 ```
 
 ## Directory Structure
@@ -56,13 +56,13 @@ bun typecheck              # TypeScript check
 
 ## Development Workflow
 
-1. **Start server**: `bun dev` in `apps/server` (or use root `bun dev` via Turbo).
-2. **Start desktop**: `bun dev` in `apps/desktop`.
+1. **Start server**: `bun run dev` in `apps/server` (or use root `bun run dev` via Turbo).
+2. **Start desktop**: `bun run dev` in `apps/desktop`.
 3. **Connection**: Main process polls `localhost:3000` until responsive, then opens BrowserWindow.
 
 ## Production Build Workflow
 
-From monorepo root, run `bun dist` to execute the full pipeline automatically (via Turbo task dependencies):
+From monorepo root, run `bun run dist` to execute the full pipeline automatically (via Turbo task dependencies):
 
 1. **Build server**: `apps/server` → `vite build` → `.output/`
 2. **Compile server**: `apps/server` → `bun compile.ts --target ...` → `out/server-{os}-{arch}`
@@ -70,8 +70,8 @@ From monorepo root, run `bun dist` to execute the full pipeline automatically (v
 
 The `electron-builder.yml` `extraResources` config reads binaries directly from `../server/out/`, no manual copy needed.
 
-To build for a specific platform explicitly, use `bun dist:linux` / `bun dist:mac` / `bun dist:win` in `apps/desktop`.
-For single-arch output, use `bun dist:linux:x64`, `bun dist:linux:arm64`, `bun dist:mac:x64`, or `bun dist:mac:arm64`.
+To build for a specific platform explicitly, use `bun run dist:linux` / `bun run dist:mac` / `bun run dist:win` in `apps/desktop`.
+For single-arch output, use `bun run dist:linux:x64`, `bun run dist:linux:arm64`, `bun run dist:mac:x64`, or `bun run dist:mac:arm64`.
 
 ## Development Principles
 
diff --git a/apps/server/AGENTS.md b/apps/server/AGENTS.md
index 5360072..1af6b86 100644
--- a/apps/server/AGENTS.md
+++ b/apps/server/AGENTS.md
@@ -4,7 +4,7 @@ TanStack Start fullstack web app with ORPC (contract-first RPC).
 
 ## Tech Stack
 
-> **⚠️ This project uses Bun — NOT Node.js / npm. All commands use `bun`. Never use `npm`, `npx`, or `node`.**
+> **⚠️ This project uses Bun — NOT Node.js / npm. All commands use `bun`. Always use `bun run <script>` (not `bun <script>`) to avoid conflicts with Bun built-in subcommands. Never use `npm`, `npx`, or `node`.**
 
 - **Framework**: TanStack Start (React 19 SSR, file-based routing)
 - **Runtime**: Bun — **NOT Node.js**
@@ -20,33 +20,33 @@ TanStack Start fullstack web app with ORPC (contract-first RPC).
 
 ```bash
 # Development
-bun dev                    # Vite dev server (localhost:3000)
-bun db:studio              # Drizzle Studio GUI
+bun run dev                    # Vite dev server (localhost:3000)
+bun run db:studio              # Drizzle Studio GUI
 
 # Build
-bun build                  # Production build → .output/
-bun compile                # Compile to standalone binary (current platform, depends on build)
-bun compile:darwin         # Compile for macOS (arm64 + x64)
-bun compile:darwin:arm64   # Compile for macOS arm64
-bun compile:darwin:x64     # Compile for macOS x64
-bun compile:linux          # Compile for Linux (x64 + arm64)
-bun compile:linux:arm64    # Compile for Linux arm64
-bun compile:linux:x64      # Compile for Linux x64
-bun compile:windows        # Compile for Windows (default: x64)
-bun compile:windows:x64    # Compile for Windows x64
+bun run build                  # Production build → .output/
+bun run compile                # Compile to standalone binary (current platform, depends on build)
+bun run compile:darwin         # Compile for macOS (arm64 + x64)
+bun run compile:darwin:arm64   # Compile for macOS arm64
+bun run compile:darwin:x64     # Compile for macOS x64
+bun run compile:linux          # Compile for Linux (x64 + arm64)
+bun run compile:linux:arm64    # Compile for Linux arm64
+bun run compile:linux:x64      # Compile for Linux x64
+bun run compile:windows        # Compile for Windows (default: x64)
+bun run compile:windows:x64    # Compile for Windows x64
 
 # Code Quality
-bun fix                    # Biome auto-fix
-bun typecheck              # TypeScript check
+bun run fix                    # Biome auto-fix
+bun run typecheck              # TypeScript check
 
 # Database
-bun db:generate            # Generate migrations from schema
-bun db:migrate             # Run migrations
-bun db:push                # Push schema directly (dev only)
+bun run db:generate            # Generate migrations from schema
+bun run db:migrate             # Run migrations
+bun run db:push                # Push schema directly (dev only)
 
 # Testing (not yet configured)
-bun test path/to/test.ts   # Run single test
-bun test -t "pattern"      # Run tests matching pattern
+bun test path/to/test.ts       # Run single test
+bun test -t "pattern"          # Run tests matching pattern
 ```
 
 ## Directory Structure
@@ -257,7 +257,7 @@ export const env = createEnv({
 ## Critical Rules
 
 **DO:**
-- Run `bun fix` before committing
+- Run `bun run fix` before committing
 - Use `@/*` path aliases
 - Include `createdAt`/`updatedAt` on all tables
 - Use `ORPCError` with proper codes
diff --git a/turbo.json b/turbo.json
index af7a524..bfdc5b9 100644
--- a/turbo.json
+++ b/turbo.json
@@ -14,12 +14,7 @@
       "cache": false
     },
     "typecheck": {
-      "inputs": [
-        "package.json",
-        "tsconfig.json",
-        "tsconfig.*.json",
-        "**/*.{ts,tsx,d.ts}"
-      ],
+      "inputs": ["package.json", "tsconfig.json", "tsconfig.*.json", "**/*.{ts,tsx,d.ts}"],
       "outputs": []
     }
   },