chore(desktop): 添加 win-x64 构建目标

chore(desktop): 禁用 mac 和 win 平台的 CEF 捆绑
refactor(desktop): 使用预分配端口替代 stdout 解析获取服务器端口
2026-02-07 21:04:39 +08:00 · 2026-02-07 20:57:58 +08:00 · 2026-02-07 19:32:56 +08:00 · 2026-02-07 19:11:28 +08:00 · 2026-02-07 19:10:33 +08:00 · 2026-02-07 18:49:50 +08:00
47 changed files with 1931 additions and 7157 deletions
--- a/.sisyphus/plans/electrobun-prod-mode.md
+++ b/.sisyphus/plans/electrobun-prod-mode.md
@@ -0,0 +1,798 @@
+# Electrobun Desktop: Production Mode via Child Process Architecture
+
+## TL;DR
+
+> **Quick Summary**: Redesign the Electrobun desktop app to support production mode by spawning the TanStack Start server as a child process. Currently only dev mode works (hardcoded `localhost:3000`). The desktop will detect dev/prod mode, spawn the server with `PORT=0` in prod, parse the actual port from stdout, and open the BrowserWindow.
+>
+> **Deliverables**:
+> - Rewritten `apps/desktop/src/bun/index.ts` with dev/prod mode support
+> - Updated `apps/desktop/electrobun.config.ts` with `build.copy` and platform configs
+> - Cross-workspace build dependency in turbo pipeline
+> - Updated `apps/desktop/AGENTS.md` reflecting new architecture
+>
+> **Estimated Effort**: Medium
+> **Parallel Execution**: YES - 2 waves
+> **Critical Path**: Tasks 1,2,3 (parallel) → Task 4 → Task 5
+
+---
+
+## Context
+
+### Original Request
+Redesign the Electrobun desktop app to support production mode. The desktop app should spawn the TanStack Start server as a child process, detect dev vs prod mode at runtime, use system-assigned ports for security, and handle server lifecycle (crash, quit).
+
+### Confirmed Decisions
+- **Architecture**: Desktop spawns server as child process via `Bun.spawn`
+- **Server artifact**: `.output/server/index.mjs` (not compiled binary) — Electrobun already bundles Bun
+- **Port strategy**: `PORT=0` (system-assigned), `HOST=127.0.0.1`
+- **Dev/Prod detection**: `process.env.ELECTROBUN_BUILD_ENV` (see Defaults Applied below)
+- **Target platforms**: All (Linux, macOS, Windows)
+- **DATABASE_URL**: Pass-through via env var, no special handling
+- **Crash handling**: MVP — log error to stderr, exit process
+
+### Research Findings
+
+**Electrobun APIs (verified from source code):**
+- `build.copy` supports paths outside the project directory (e.g., `../server/.output`). Source paths are resolved relative to the project root. Destinations map into `Resources/app/` in the bundle.
+- `PATHS` exported from `electrobun/bun` provides `RESOURCES_FOLDER` (absolute path to `Resources/`) and `VIEWS_FOLDER` (`Resources/app/views/`).
+- `process.execPath` in a bundled Electrobun app points to the bundled Bun binary.
+- `Electrobun.events.on('before-quit', callback)` fires before app quit. Callback receives an event with `response({ allow: false })` to cancel quit.
+- `ELECTROBUN_BUILD_ENV` is set by the Electrobun CLI: `"dev"` for `electrobun dev`, `"stable"` for `electrobun build --env=stable`.
+
+**Server startup behavior (verified from built output):**
+- `.output/server/index.mjs` uses `Bun.serve` via the `h3+srvx` adapter (Nitro bun preset).
+- Startup log format: `➜ Listening on: http://<address>:<port>/`
+- The log uses the actual assigned address/port, not the requested one. So `PORT=0` will log the real port.
+- `DATABASE_URL` is validated at startup via Zod (`@t3-oss/env-core`). Missing = immediate crash.
+- The `.output/server/` directory contains `index.mjs` plus `_libs/` with bundled dependencies.
+
+**Turbo pipeline:**
+- Root `turbo.json` has `build.dependsOn: ["^build"]` which only builds workspace *dependencies*.
+- Desktop does NOT depend on server in `package.json`, so `^build` won't trigger server build.
+- Need explicit cross-workspace dependency via desktop's `turbo.json`.
+
+### Metis Review
+**Identified Gaps** (addressed):
+- Dev/prod detection mechanism: Switched from custom `ELECTROBUN_DEV` to built-in `ELECTROBUN_BUILD_ENV`
+- Server startup timeout: Added explicit timeout with error reporting
+- Port parsing failure: Plan includes fallback and error handling
+- Server crash during runtime: Watching `subprocess.exited` promise
+- `cwd` for spawned server: Must set to server directory for relative import resolution
+- Cross-platform considerations: `ELECTROBUN_BUILD_ENV` works everywhere (no `cross-env` needed)
+
+### Unknowns Resolved
+
+| Unknown | Resolution |
+|---------|------------|
+| Does `build.copy` support paths outside project? | **YES** — uses `cpSync` with source resolved from project root. `../server/.output` works. |
+| Runtime API for resolving bundled resource paths? | **`PATHS.RESOURCES_FOLDER`** from `electrobun/bun`. Copied files land in `Resources/app/{dest}/`. |
+| Does Nitro log actual port with PORT=0? | **YES** — format: `➜ Listening on: http://<addr>:<port>/` via h3+srvx adapter. |
+| How does Electrobun detect dev mode? | **`ELECTROBUN_BUILD_ENV`** env var set by CLI. Values: `dev`, `canary`, `stable`. |
+
+---
+
+## Work Objectives
+
+### Core Objective
+Enable the Electrobun desktop app to run in production mode by spawning the TanStack Start server as a managed child process, while preserving existing dev mode behavior.
+
+### Concrete Deliverables
+- `apps/desktop/src/bun/index.ts` — Complete rewrite with dual-mode support
+- `apps/desktop/electrobun.config.ts` — `build.copy` + all-platform configs
+- `apps/desktop/turbo.json` — Cross-workspace build dependency
+- `apps/desktop/AGENTS.md` — Accurate documentation of new architecture
+
+### Definition of Done
+- [ ] `bun typecheck` passes from monorepo root (zero errors)
+- [ ] `bun build` from root succeeds: server builds first, then desktop bundles server output
+- [ ] `bun dev` from root still starts both apps (dev mode preserved)
+- [ ] Desktop `index.ts` has zero hardcoded URLs (all dynamic)
+
+### Must Have
+- Dev mode: poll external `localhost:3000`, open window when ready (existing behavior, refactored)
+- Prod mode: spawn server via `Bun.spawn`, parse port from stdout, open window
+- Server bound to `127.0.0.1` only (no network exposure)
+- `PORT=0` for system-assigned port (no conflicts)
+- Server process killed on app quit (via `before-quit` event)
+- Server crash detection (watch `exited` promise, log error, exit app)
+- Startup timeout with clear error message
+- Server `cwd` set to its own directory (for relative import resolution)
+- `DATABASE_URL` passed through from parent environment
+
+### Must NOT Have (Guardrails)
+- No hardcoded port numbers (not even 3000 — use a named constant `DEV_SERVER_URL`)
+- No `as any`, `@ts-ignore`, or `@ts-expect-error`
+- No empty catch blocks — always handle or re-throw
+- No `npm`, `npx`, `node` — Bun only
+- No manual `useMemo`/`useCallback` (not relevant here, but per project rules)
+- No suppressed type errors — fix them properly
+- No custom env var for dev detection — use built-in `ELECTROBUN_BUILD_ENV`
+- No compiled server binary — use `.output/server/index.mjs` with bundled Bun
+- Do NOT edit `apps/server/` — only `apps/desktop/` files change
+- Do NOT add `@furtherverse/server` as a package dependency of desktop (use turbo cross-workspace dependency instead)
+
+---
+
+## Verification Strategy
+
+> **UNIVERSAL RULE: ZERO HUMAN INTERVENTION**
+>
+> ALL tasks in this plan MUST be verifiable WITHOUT any human action.
+> Every criterion is verified by running a command or using a tool.
+
+### Test Decision
+- **Infrastructure exists**: NO (no test framework in this project)
+- **Automated tests**: NO (per project state — `AGENTS.md` says "No test framework configured yet")
+- **Framework**: None
+- **Agent-Executed QA**: ALWAYS (mandatory for all tasks)
+
+---
+
+## Execution Strategy
+
+### Parallel Execution Waves
+
+```
+Wave 1 (Start Immediately — all independent, different files):
+├── Task 1: Update electrobun.config.ts (build.copy + platform configs)
+├── Task 2: Update turbo.json (cross-workspace build dependency)
+└── Task 3: Rewrite index.ts (complete dev/prod mode implementation)
+
+Wave 2 (After Wave 1 — needs final state of all files):
+├── Task 4: Rewrite AGENTS.md (documentation reflecting new architecture)
+└── Task 5: End-to-end verification (typecheck + build pipeline)
+```
+
+### Dependency Matrix
+
+| Task | Depends On | Blocks | Can Parallelize With |
+|------|------------|--------|---------------------|
+| 1 | None | 4, 5 | 2, 3 |
+| 2 | None | 4, 5 | 1, 3 |
+| 3 | None | 4, 5 | 1, 2 |
+| 4 | 1, 2, 3 | 5 | None |
+| 5 | 1, 2, 3, 4 | None | None (final) |
+
+### Agent Dispatch Summary
+
+| Wave | Tasks | Recommended Agents |
+|------|-------|-------------------|
+| 1 | 1, 2, 3 | Tasks 1,2: `delegate_task(category="quick")`. Task 3: `delegate_task(category="unspecified-high")` |
+| 2 | 4, 5 | Task 4: `delegate_task(category="writing")`. Task 5: `delegate_task(category="quick")` |
+
+---
+
+## TODOs
+
+- [ ] 1. Update `apps/desktop/electrobun.config.ts` — Add build.copy and platform configs
+
+  **What to do**:
+  - Add `build.copy` to include the server's Nitro build output in the desktop bundle:
+    ```typescript
+    copy: {
+      '../server/.output': 'server-output',
+    }
+    ```
+    This copies `apps/server/.output/` (the entire Nitro build output) into `Resources/app/server-output/` in the Electrobun bundle. The full server entry point will be at `Resources/app/server-output/server/index.mjs`.
+  - Add `macOS` platform config block (currently only `linux` exists):
+    ```typescript
+    macOS: {
+      bundleCEF: true,
+    }
+    ```
+  - Add `windows` platform config block:
+    ```typescript
+    windows: {
+      bundleCEF: true,
+    }
+    ```
+  - Verify the exact property names by checking Electrobun's `ElectrobunConfig` type definition. The `linux` block already uses `bundleCEF: true`, so follow the same pattern for other platforms. If the type doesn't support `macOS`/`windows` yet, skip those and leave a `// TODO:` comment explaining what's needed.
+  - Preserve existing config values exactly (app name, identifier, version, bun entrypoint, linux config).
+
+  **Must NOT do**:
+  - Do not change the app name, identifier, or version
+  - Do not change the bun entrypoint path
+  - Do not remove the existing `linux` config
+  - Do not add dependencies or scripts
+
+  **Recommended Agent Profile**:
+  - **Category**: `quick`
+    - Reason: Single file, small config change, clear specification
+  - **Skills**: `[]`
+    - No specialized skills needed — straightforward TypeScript config edit
+  - **Skills Evaluated but Omitted**:
+    - `frontend-ui-ux`: No UI work involved
+
+  **Parallelization**:
+  - **Can Run In Parallel**: YES
+  - **Parallel Group**: Wave 1 (with Tasks 2, 3)
+  - **Blocks**: Tasks 4, 5
+  - **Blocked By**: None (can start immediately)
+
+  **References**:
+
+  **Pattern References** (existing code to follow):
+  - `apps/desktop/electrobun.config.ts` — Current config structure. The `linux.bundleCEF: true` pattern should be replicated for other platforms. The `build.bun.entrypoint` key shows where build config lives.
+
+  **API/Type References** (contracts to implement against):
+  - The `ElectrobunConfig` type from `electrobun` — imported via `import type { ElectrobunConfig } from 'electrobun'`. Check its definition (likely in `node_modules/electrobun/`) to verify exact property names for `copy`, `macOS`, `windows`.
+
+  **External References**:
+  - Electrobun `build.copy` syntax: copies source (relative to project root) into `Resources/app/{dest}/` in the bundle. Uses `cpSync` with `dereference: true`.
+
+  **WHY Each Reference Matters**:
+  - `electrobun.config.ts`: You're editing this file — need to know its current shape to preserve existing values
+  - `ElectrobunConfig` type: Must match the type definition exactly — don't guess property names
+
+  **Acceptance Criteria**:
+  - [ ] `build.copy` key exists with `'../server/.output': 'server-output'` mapping
+  - [ ] Platform configs added for all three platforms (or TODO comments if types don't support them)
+  - [ ] Existing config values unchanged (app.name = 'Desktop', etc.)
+  - [ ] File passes `bun typecheck` (no type errors)
+
+  **Agent-Executed QA Scenarios:**
+
+  ```
+  Scenario: Config file is valid TypeScript with correct types
+    Tool: Bash
+    Preconditions: None
+    Steps:
+      1. Run: bun typecheck (from apps/desktop/)
+      2. Assert: Exit code 0
+      3. Assert: No errors mentioning electrobun.config.ts
+    Expected Result: TypeScript compilation succeeds
+    Evidence: Terminal output captured
+
+  Scenario: build.copy key has correct structure
+    Tool: Bash (grep)
+    Preconditions: File has been edited
+    Steps:
+      1. Read apps/desktop/electrobun.config.ts
+      2. Assert: Contains '../server/.output'
+      3. Assert: Contains 'server-output'
+      4. Assert: File still contains 'satisfies ElectrobunConfig'
+    Expected Result: Config has copy mapping and type annotation
+    Evidence: File contents
+  ```
+
+  **Commit**: YES (groups with 2)
+  - Message: `feat(desktop): add build.copy for server bundle and platform configs`
+  - Files: `apps/desktop/electrobun.config.ts`
+  - Pre-commit: `bun typecheck` (from `apps/desktop/`)
+
+---
+
+- [ ] 2. Update `apps/desktop/turbo.json` — Add cross-workspace build dependency
+
+  **What to do**:
+  - Add `dependsOn` to the existing `build` task to ensure the server builds before the desktop:
+    ```json
+    {
+      "tasks": {
+        "build": {
+          "dependsOn": ["@furtherverse/server#build"],
+          "outputs": ["build/**", "artifacts/**"]
+        }
+      }
+    }
+    ```
+  - This tells Turbo: "before running `build` for `@furtherverse/desktop`, first run `build` for `@furtherverse/server`."
+  - This ensures `apps/server/.output/` exists when `electrobun build` runs and tries to `build.copy` from `../server/.output`.
+  - Preserve the existing `outputs` array exactly.
+
+  **Must NOT do**:
+  - Do not modify the root `turbo.json` — only `apps/desktop/turbo.json`
+  - Do not remove existing `outputs`
+  - Do not add other tasks or change other config
+
+  **Recommended Agent Profile**:
+  - **Category**: `quick`
+    - Reason: Single file, one-line JSON change
+  - **Skills**: `[]`
+    - No specialized skills needed
+  - **Skills Evaluated but Omitted**:
+    - `git-master`: Commit will be grouped with Task 1
+
+  **Parallelization**:
+  - **Can Run In Parallel**: YES
+  - **Parallel Group**: Wave 1 (with Tasks 1, 3)
+  - **Blocks**: Tasks 4, 5
+  - **Blocked By**: None (can start immediately)
+
+  **References**:
+
+  **Pattern References** (existing code to follow):
+  - `apps/desktop/turbo.json` — Current file with `build.outputs` already defined. You're adding `dependsOn` alongside it.
+  - `turbo.json` (root) — Shows existing turbo patterns like `build.dependsOn: ["^build"]`. The root already uses `^build` for workspace dependencies, but since desktop doesn't list server as a package dependency, we need an explicit cross-workspace reference.
+
+  **API/Type References**:
+  - Turbo `dependsOn` syntax: `"@furtherverse/server#build"` means "run the `build` task in the `@furtherverse/server` workspace".
+
+  **Documentation References**:
+  - `apps/server/package.json` — The package name is `@furtherverse/server` (verify this is the exact name used in the `dependsOn` reference).
+
+  **WHY Each Reference Matters**:
+  - `apps/desktop/turbo.json`: You're editing this file — preserve existing outputs
+  - `apps/server/package.json`: Need exact package name for the cross-workspace reference
+  - Root `turbo.json`: Context for existing turbo patterns in this project
+
+  **Acceptance Criteria**:
+  - [ ] `apps/desktop/turbo.json` has `dependsOn: ["@furtherverse/server#build"]` in the build task
+  - [ ] Existing `outputs` array is preserved
+  - [ ] Valid JSON (no syntax errors)
+
+  **Agent-Executed QA Scenarios:**
+
+  ```
+  Scenario: turbo.json is valid JSON with correct structure
+    Tool: Bash
+    Preconditions: File has been edited
+    Steps:
+      1. Run: bun -e "JSON.parse(require('fs').readFileSync('apps/desktop/turbo.json', 'utf8'))"
+      2. Assert: Exit code 0 (valid JSON)
+      3. Read the file and verify structure contains both dependsOn and outputs
+    Expected Result: Valid JSON with both keys present
+    Evidence: Terminal output captured
+
+  Scenario: Turbo resolves the cross-workspace dependency
+    Tool: Bash
+    Preconditions: turbo.json updated
+    Steps:
+      1. Run: bunx turbo build --dry-run --filter=@furtherverse/desktop (from monorepo root)
+      2. Assert: Output shows @furtherverse/server#build runs BEFORE @furtherverse/desktop#build
+    Expected Result: Server build is listed as a dependency in the dry-run output
+    Evidence: Terminal output showing task execution order
+  ```
+
+  **Commit**: YES (groups with 1)
+  - Message: `feat(desktop): add build.copy for server bundle and platform configs`
+  - Files: `apps/desktop/turbo.json`
+  - Pre-commit: Valid JSON check
+
+---
+
+- [ ] 3. Rewrite `apps/desktop/src/bun/index.ts` — Complete dev/prod mode implementation
+
+  **What to do**:
+
+  This is the core task. Completely rewrite `index.ts` to support both dev and prod modes. The new file should have this structure:
+
+  **A. Imports and Constants**:
+  ```typescript
+  import Electrobun, { BrowserWindow } from 'electrobun/bun'
+  // Import PATHS — verify exact import syntax from electrobun/bun type definitions
+  // It may be: import { PATHS } from 'electrobun/bun'
+  // Or it may be on the Electrobun default export: Electrobun.PATHS
+  // CHECK the type definitions in node_modules/electrobun/ before writing
+  import { join, dirname } from 'path'
+
+  const DEV_SERVER_URL = 'http://localhost:3000'
+  const SERVER_READY_TIMEOUT_MS = 30_000
+  const PORT_PATTERN = /Listening on:?\s*https?:\/\/[^\s:]+:(\d+)/
+  ```
+
+  **B. `isDev()` function**:
+  - Check `process.env.ELECTROBUN_BUILD_ENV === 'dev'`
+  - If `ELECTROBUN_BUILD_ENV` is not set, default to `true` (dev mode) — safe fallback
+  - Return a boolean
+
+  **C. `getServerEntryPath()` function**:
+  - Use `PATHS.RESOURCES_FOLDER` (or equivalent) to resolve the bundled server entry
+  - Path: `join(PATHS.RESOURCES_FOLDER, 'app', 'server-output', 'server', 'index.mjs')`
+  - **IMPORTANT**: Verify `PATHS.RESOURCES_FOLDER` points to `Resources/` and that `build.copy` destinations land in `Resources/app/`. If the pathing is different, adjust accordingly. The executor MUST verify by checking Electrobun's source or type definitions.
+
+  **D. `waitForServer(url, timeoutMs)` function** (preserved from current code):
+  - Polls a URL with `fetch` HEAD requests
+  - Returns `true` when server responds with `response.ok`
+  - Returns `false` on timeout
+  - Uses `Bun.sleep(100)` between attempts
+  - Catches fetch errors silently (server not up yet)
+
+  **E. `spawnServer()` function** (NEW — the critical piece):
+  - Returns a `Promise<{ process: Subprocess; url: string }>`
+  - Implementation:
+    1. Resolve the server entry path via `getServerEntryPath()`
+    2. Resolve the server directory via `dirname(serverEntryPath)` — used as `cwd`
+    3. Spawn with `Bun.spawn`:
+       ```typescript
+       const serverProc = Bun.spawn([process.execPath, serverEntryPath], {
+         cwd: serverDir,
+         env: {
+           ...process.env,
+           PORT: '0',
+           HOST: '127.0.0.1',
+         },
+         stdout: 'pipe',
+         stderr: 'pipe',
+       })
+       ```
+    4. Read stdout as a stream to find the port:
+       - Use `serverProc.stdout` (a `ReadableStream<Uint8Array>`)
+       - Create a reader, accumulate chunks into a text buffer
+       - Test buffer against `PORT_PATTERN` regex after each chunk
+       - When match found: extract port, resolve promise with `{ process: serverProc, url: 'http://127.0.0.1:${port}' }`
+    5. Implement a timeout:
+       - Use `setTimeout` to reject the promise after `SERVER_READY_TIMEOUT_MS`
+       - On timeout, kill the server process before rejecting
+    6. Handle early exit:
+       - If stdout ends (stream done) before port is found, reject with error
+       - Include any stderr output in the error message for debugging
+
+  **F. `main()` async function**:
+  - Log startup message
+  - Branch on `isDev()`:
+    - **Dev mode**:
+      1. Log: "Dev mode: waiting for external server..."
+      2. Call `waitForServer(DEV_SERVER_URL)`
+      3. If timeout: log error with instructions (`"Run: bun dev in apps/server"`), `process.exit(1)`
+      4. Set `serverUrl = DEV_SERVER_URL`
+    - **Prod mode**:
+      1. Log: "Production mode: starting embedded server..."
+      2. Call `spawnServer()`
+      3. If error: log error, `process.exit(1)`
+      4. Store returned `process` and `url`
+  - Create `BrowserWindow` with the resolved `serverUrl`:
+    ```typescript
+    new BrowserWindow({
+      title: 'Furtherverse',
+      url: serverUrl,
+      frame: { x: 100, y: 100, width: 1200, height: 800 },
+      renderer: 'cef',
+    })
+    ```
+  - Register lifecycle handlers:
+    - `Electrobun.events.on('before-quit', ...)`: Kill server process if it exists
+    - Watch `serverProcess.exited` (if in prod mode): When server exits unexpectedly, log the exit code and stderr, then `process.exit(1)`
+
+  **G. Top-level execution**:
+  ```typescript
+  main().catch((error) => {
+    console.error('Failed to start:', error)
+    process.exit(1)
+  })
+  ```
+
+  **Critical implementation details**:
+  - The `PORT_PATTERN` regex must handle multiple log formats:
+    - `➜ Listening on: http://localhost:54321/` (srvx format)
+    - `Listening on http://127.0.0.1:54321` (node-server format)
+    - `Listening on http://[::]:54321` (IPv6 format)
+  - The regex `/Listening on:?\s*https?:\/\/[^\s:]+:(\d+)/` captures the port from all these formats.
+  - `cwd` MUST be set to the server directory (`dirname(serverEntryPath)`), not the app root. Nitro resolves internal `_libs/` imports relative to its directory.
+  - `process.execPath` in an Electrobun bundle points to the bundled Bun binary — this is what runs the server.
+  - `stderr: 'pipe'` — capture stderr for crash diagnostics but don't block on it during startup.
+
+  **Must NOT do**:
+  - Do not hardcode port numbers anywhere (use `PORT=0` and parse result)
+  - Do not use `as any` or type assertions to work around issues
+  - Do not use `child_process` module — use `Bun.spawn` (native Bun API)
+  - Do not bind server to `0.0.0.0` — always use `127.0.0.1`
+  - Do not leave the `waitForServer` function unused in dev mode
+  - Do not use synchronous I/O for stdout reading
+
+  **Recommended Agent Profile**:
+  - **Category**: `unspecified-high`
+    - Reason: Complex async logic (stream parsing, subprocess lifecycle, timeout management), multiple code paths (dev/prod), error handling across process boundaries. This is the architectural centerpiece.
+  - **Skills**: `[]`
+    - No specialized skills needed — pure Bun/TypeScript with Electrobun APIs
+  - **Skills Evaluated but Omitted**:
+    - `frontend-ui-ux`: No UI work — this is backend/process management code
+    - `playwright`: No browser testing needed for this task
+
+  **Parallelization**:
+  - **Can Run In Parallel**: YES
+  - **Parallel Group**: Wave 1 (with Tasks 1, 2)
+  - **Blocks**: Tasks 4, 5
+  - **Blocked By**: None (can start immediately — edits a different file from Tasks 1, 2)
+
+  **References**:
+
+  **Pattern References** (existing code to follow):
+  - `apps/desktop/src/bun/index.ts` — Current implementation. Preserve the `waitForServer` polling pattern (slightly refactored). Keep the `BrowserWindow` config (title, frame dimensions, renderer). Keep the top-level `main().catch(...)` pattern.
+  - `apps/desktop/src/bun/index.ts:1` — Current import: `import Electrobun, { BrowserWindow } from 'electrobun/bun'`. Extend this to also import `PATHS` (verify exact export name from type definitions).
+
+  **API/Type References** (contracts to implement against):
+  - `electrobun/bun` module — Exports `Electrobun` (default), `BrowserWindow` (named), and `PATHS` (named — verify). Check `node_modules/electrobun/` for exact type definitions.
+  - `Bun.spawn` API — Returns `Subprocess` with `.stdout` (ReadableStream when piped), `.stderr`, `.exited` (Promise<number>), `.kill()`.
+  - `PATHS.RESOURCES_FOLDER` — Absolute path to `Resources/` directory in the bundle. Verify by reading the Paths.ts source in electrobun package.
+
+  **Documentation References**:
+  - `apps/desktop/AGENTS.md` — Mentions production mode architecture (aspirational, but gives intent)
+
+  **External References**:
+  - Electrobun lifecycle events: `Electrobun.events.on('before-quit', callback)` — callback can call `event.response({ allow: false })` to cancel. Source: `electrobun/src/bun/core/Utils.ts`.
+  - Electrobun `PATHS`: Source at `electrobun/src/bun/core/Paths.ts`. Contains `RESOURCES_FOLDER` and `VIEWS_FOLDER`.
+  - Bun `Subprocess` docs: `stdout` is `ReadableStream<Uint8Array>` when `stdout: 'pipe'`.
+
+  **WHY Each Reference Matters**:
+  - Current `index.ts`: Preserving the `waitForServer` pattern, `BrowserWindow` config, and error handling style. You're rewriting this file, so understand what to keep vs. replace.
+  - `electrobun/bun` types: MUST verify `PATHS` export name and shape before using it. Don't assume — check.
+  - `Bun.spawn` API: Core to the entire prod mode implementation. Understand `stdout` stream reading.
+  - Lifecycle events: `before-quit` is where server cleanup happens. Understand the event contract.
+
+  **Acceptance Criteria**:
+  - [ ] File compiles: `bun typecheck` passes (from `apps/desktop/`)
+  - [ ] No hardcoded port numbers (grep for `:3000` — should only appear in `DEV_SERVER_URL` constant)
+  - [ ] `isDev()` function uses `process.env.ELECTROBUN_BUILD_ENV`
+  - [ ] `spawnServer()` uses `PORT=0`, `HOST=127.0.0.1`, `process.execPath`
+  - [ ] `spawnServer()` sets `cwd` to `dirname(serverEntryPath)`
+  - [ ] `before-quit` handler kills server process
+  - [ ] Server crash watcher exists (watches `subprocess.exited`)
+  - [ ] Timeout handling exists in both dev and prod paths
+  - [ ] All Biome rules pass: `bun fix` produces no changes
+
+  **Agent-Executed QA Scenarios:**
+
+  ```
+  Scenario: File compiles with zero type errors
+    Tool: Bash
+    Preconditions: File has been rewritten
+    Steps:
+      1. Run: bun typecheck (from apps/desktop/)
+      2. Assert: Exit code 0
+      3. Assert: No errors in output
+    Expected Result: Clean TypeScript compilation
+    Evidence: Terminal output captured
+
+  Scenario: No hardcoded ports outside DEV_SERVER_URL
+    Tool: Bash (grep)
+    Preconditions: File has been rewritten
+    Steps:
+      1. Search apps/desktop/src/bun/index.ts for literal ':3000'
+      2. Assert: Only occurrence is in the DEV_SERVER_URL constant definition
+      3. Search for literal '3000' — should only appear once
+    Expected Result: Port 3000 only in constant, nowhere else
+    Evidence: Grep output
+
+  Scenario: Code passes Biome lint/format
+    Tool: Bash
+    Preconditions: File has been rewritten
+    Steps:
+      1. Run: bun fix (from apps/desktop/)
+      2. Run: git diff apps/desktop/src/bun/index.ts
+      3. Assert: No diff (bun fix made no changes)
+    Expected Result: Code already conforms to Biome rules
+    Evidence: Empty git diff
+
+  Scenario: Required patterns present in source
+    Tool: Bash (grep)
+    Preconditions: File has been rewritten
+    Steps:
+      1. Grep for 'ELECTROBUN_BUILD_ENV' — Assert: found
+      2. Grep for 'Bun.spawn' — Assert: found
+      3. Grep for 'process.execPath' — Assert: found
+      4. Grep for 'PORT.*0' — Assert: found
+      5. Grep for '127.0.0.1' — Assert: found
+      6. Grep for 'before-quit' — Assert: found
+      7. Grep for '.exited' — Assert: found (crash watcher)
+      8. Grep for 'dirname' — Assert: found (cwd for server)
+    Expected Result: All required patterns present
+    Evidence: Grep results for each pattern
+  ```
+
+  **Commit**: YES
+  - Message: `feat(desktop): implement production mode with child process server`
+  - Files: `apps/desktop/src/bun/index.ts`
+  - Pre-commit: `bun typecheck && bun fix`
+
+---
+
+- [ ] 4. Rewrite `apps/desktop/AGENTS.md` — Document new architecture
+
+  **What to do**:
+  - Completely rewrite `AGENTS.md` to reflect the actual implemented architecture
+  - Document:
+    - **Architecture overview**: Desktop spawns server as child process in prod, connects to external server in dev
+    - **Dev mode**: How it works (polls localhost:3000, requires server running separately)
+    - **Prod mode**: How it works (spawns server from bundle, PORT=0, parses port from stdout)
+    - **Environment detection**: `ELECTROBUN_BUILD_ENV` values (`dev`, `canary`, `stable`)
+    - **Build pipeline**: Server must build before desktop (turbo dependency), `build.copy` bundles output
+    - **Key files**: `src/bun/index.ts` (main process), `electrobun.config.ts` (build config)
+    - **Environment variables**: `DATABASE_URL` (required, passed to server), `ELECTROBUN_BUILD_ENV` (auto-set by CLI)
+    - **Server lifecycle**: Spawned on start, killed on quit, crash = exit
+    - **Commands**: `bun dev`, `bun build`, `bun typecheck`, `bun fix`
+  - Follow the style and conventions of the root `AGENTS.md` and `apps/server/AGENTS.md`
+  - Be factual — only document what actually exists, not aspirational features
+
+  **Must NOT do**:
+  - Do not document features that don't exist
+  - Do not copy content from the server's AGENTS.md verbatim
+  - Do not include implementation details that belong in code comments
+
+  **Recommended Agent Profile**:
+  - **Category**: `writing`
+    - Reason: Documentation task requiring clear technical writing
+  - **Skills**: `[]`
+    - No specialized skills needed
+  - **Skills Evaluated but Omitted**:
+    - `frontend-ui-ux`: Not a UI task
+
+  **Parallelization**:
+  - **Can Run In Parallel**: NO
+  - **Parallel Group**: Wave 2
+  - **Blocks**: Task 5
+  - **Blocked By**: Tasks 1, 2, 3 (needs to know final state of all files)
+
+  **References**:
+
+  **Pattern References** (existing code to follow):
+  - `AGENTS.md` (root) — Follow same structure: Overview, Build Commands, Code Style, Directory Structure sections
+  - `apps/server/AGENTS.md` — Follow same style for app-specific documentation. Use this as a template for tone and detail level.
+
+  **Content References** (what to document):
+  - `apps/desktop/src/bun/index.ts` — The rewritten file (Task 3 output). Document its behavior, not its code.
+  - `apps/desktop/electrobun.config.ts` — The updated config (Task 1 output). Document build.copy and platform configs.
+  - `apps/desktop/turbo.json` — The updated turbo config (Task 2 output). Document the build dependency.
+
+  **WHY Each Reference Matters**:
+  - Root `AGENTS.md`: Template for documentation style
+  - Server `AGENTS.md`: Template for app-specific docs
+  - All Task 1-3 outputs: The actual implemented behavior that must be accurately documented
+
+  **Acceptance Criteria**:
+  - [ ] File exists and is valid Markdown
+  - [ ] Documents dev mode behavior accurately
+  - [ ] Documents prod mode behavior accurately
+  - [ ] Documents `ELECTROBUN_BUILD_ENV` mechanism
+  - [ ] Documents build pipeline (server → desktop dependency)
+  - [ ] Documents `DATABASE_URL` requirement
+  - [ ] Does NOT mention features that don't exist
+  - [ ] Follows conventions from root `AGENTS.md`
+
+  **Agent-Executed QA Scenarios:**
+
+  ```
+  Scenario: AGENTS.md contains all required sections
+    Tool: Bash (grep)
+    Preconditions: File has been rewritten
+    Steps:
+      1. Grep for 'dev' or 'Dev' — Assert: found (dev mode documented)
+      2. Grep for 'prod' or 'Prod' or 'production' — Assert: found (prod mode documented)
+      3. Grep for 'ELECTROBUN_BUILD_ENV' — Assert: found
+      4. Grep for 'DATABASE_URL' — Assert: found
+      5. Grep for 'child process' or 'spawn' — Assert: found (architecture documented)
+      6. Grep for 'bun dev' — Assert: found (commands documented)
+      7. Grep for 'bun build' — Assert: found (commands documented)
+    Expected Result: All key topics are covered
+    Evidence: Grep results
+
+  Scenario: No aspirational/unimplemented features documented
+    Tool: Bash (grep)
+    Preconditions: File has been rewritten
+    Steps:
+      1. Grep for 'TODO' or 'planned' or 'future' or 'coming soon' — Assert: not found (or minimal)
+      2. Grep for 'auto-update' — Assert: not found (not implemented)
+      3. Grep for 'tray' — Assert: not found (not implemented)
+    Expected Result: Only implemented features documented
+    Evidence: Grep results showing no aspirational content
+  ```
+
+  **Commit**: YES
+  - Message: `docs(desktop): rewrite AGENTS.md to reflect production mode architecture`
+  - Files: `apps/desktop/AGENTS.md`
+  - Pre-commit: None (Markdown file)
+
+---
+
+- [ ] 5. End-to-end verification — Typecheck and build pipeline
+
+  **What to do**:
+  - Run full monorepo typecheck to ensure no type errors were introduced
+  - Run full monorepo build to verify:
+    1. Server builds first (produces `.output/`)
+    2. Desktop builds second (copies server output into bundle)
+    3. No build errors
+  - Run Biome formatting/linting check on all changed files
+  - Verify dev mode still works conceptually (no runtime test — just verify the code path exists)
+
+  **Must NOT do**:
+  - Do not fix issues in server code — only desktop code
+  - Do not modify any files unless fixing issues found during verification
+  - Do not skip any verification step
+
+  **Recommended Agent Profile**:
+  - **Category**: `quick`
+    - Reason: Running commands and checking output, no creative work
+  - **Skills**: `[]`
+    - No specialized skills needed
+  - **Skills Evaluated but Omitted**:
+    - `playwright`: No browser testing in this verification
+
+  **Parallelization**:
+  - **Can Run In Parallel**: NO
+  - **Parallel Group**: Wave 2 (sequential after Task 4)
+  - **Blocks**: None (final task)
+  - **Blocked By**: Tasks 1, 2, 3, 4
+
+  **References**:
+
+  **Documentation References**:
+  - `AGENTS.md` (root) — Build/Lint/Test commands: `bun typecheck`, `bun fix`, `bun build`
+  - `apps/desktop/package.json` — Desktop-specific scripts
+
+  **WHY Each Reference Matters**:
+  - Root `AGENTS.md`: Canonical list of verification commands
+  - Desktop `package.json`: Desktop-specific build/typecheck commands
+
+  **Acceptance Criteria**:
+  - [ ] `bun typecheck` (monorepo root) exits with code 0
+  - [ ] `bun build` (monorepo root) exits with code 0
+  - [ ] `bun fix` (monorepo root) produces no changes (all code formatted)
+  - [ ] Build output shows server building before desktop
+  - [ ] Desktop build output includes server bundle (verify in build artifacts)
+
+  **Agent-Executed QA Scenarios:**
+
+  ```
+  Scenario: Monorepo typecheck passes
+    Tool: Bash
+    Preconditions: All tasks 1-4 completed
+    Steps:
+      1. Run: bun typecheck (from monorepo root)
+      2. Assert: Exit code 0
+      3. Assert: No error output
+    Expected Result: Zero type errors across entire monorepo
+    Evidence: Terminal output captured
+
+  Scenario: Monorepo build succeeds with correct order
+    Tool: Bash
+    Preconditions: All tasks 1-4 completed
+    Steps:
+      1. Run: bun build (from monorepo root)
+      2. Assert: Exit code 0
+      3. Assert: Output shows @furtherverse/server build task runs
+      4. Assert: Output shows @furtherverse/desktop build task runs AFTER server
+    Expected Result: Build pipeline executes in correct order
+    Evidence: Terminal output showing task order
+
+  Scenario: Biome finds no issues
+    Tool: Bash
+    Preconditions: All tasks 1-4 completed
+    Steps:
+      1. Run: bun fix (from monorepo root)
+      2. Run: git diff
+      3. Assert: No changes (all code already formatted)
+    Expected Result: All code passes Biome rules
+    Evidence: Empty git diff
+
+  Scenario: Desktop build artifacts include server bundle
+    Tool: Bash
+    Preconditions: Build succeeded
+    Steps:
+      1. Search desktop build output directory for server-output/ or index.mjs
+      2. Assert: Server files are present in the desktop bundle
+    Expected Result: Server bundle is included in desktop build output
+    Evidence: File listing of build artifacts
+  ```
+
+  **Commit**: NO (verification only — no file changes unless fixing issues)
+
+---
+
+## Commit Strategy
+
+| After Task(s) | Message | Files | Verification |
+|---------------|---------|-------|--------------|
+| 1, 2 | `feat(desktop): add build.copy for server bundle and cross-workspace build dependency` | `electrobun.config.ts`, `turbo.json` | `bun typecheck` |
+| 3 | `feat(desktop): implement production mode with child process server` | `src/bun/index.ts` | `bun typecheck && bun fix` |
+| 4 | `docs(desktop): rewrite AGENTS.md to reflect production mode architecture` | `AGENTS.md` | None |
+| 5 | (no commit — verification only) | — | — |
+
+---
+
+## Success Criteria
+
+### Verification Commands
+```bash
+bun typecheck          # Expected: exit 0, no errors
+bun build              # Expected: exit 0, server builds before desktop
+bun fix                # Expected: no changes (already formatted)
+```
+
+### Final Checklist
+- [ ] All "Must Have" features present in `index.ts`
+- [ ] All "Must NOT Have" exclusions verified absent
+- [ ] All 3 verification commands pass
+- [ ] `AGENTS.md` accurately reflects implemented architecture
+- [ ] Server output is bundled into desktop build via `build.copy`
+- [ ] Turbo builds server before desktop
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -0,0 +1,178 @@
+# AGENTS.md - AI Coding Agent Guidelines
+
+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`.**
+
+- **Monorepo**: Bun workspaces + Turborepo orchestration
+- **Runtime**: Bun (see `mise.toml` for version) — **NOT Node.js**
+- **Package Manager**: Bun — **NOT npm / yarn / pnpm**
+- **Apps**:
+  - `apps/server` - TanStack Start fullstack web app (see `apps/server/AGENTS.md`)
+  - `apps/desktop` - Electrobun desktop shell, loads server in native window (see `apps/desktop/AGENTS.md`)
+- **Packages**: `packages/utils`, `packages/tsconfig` (shared configs)
+
+## Build / Lint / Test Commands
+
+### Root Commands (via Turbo)
+```bash
+bun dev            # Start all apps in dev mode
+bun build          # Build all apps
+bun fix            # Lint + format (Biome auto-fix)
+bun 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
+bun fix                   # Biome auto-fix
+bun 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
+```
+
+### Desktop App (`apps/desktop`)
+```bash
+bun dev                   # Start Electrobun dev mode (requires server dev running)
+bun build                 # Build canary release
+bun build:stable          # Build stable release
+bun fix                   # Biome auto-fix
+bun typecheck             # TypeScript check
+```
+
+### Testing
+No test framework configured yet. When adding tests:
+```bash
+bun test path/to/test.ts              # Run single test file
+bun test -t "pattern"                 # Run tests matching pattern
+```
+
+## Code Style (TypeScript)
+
+### Formatting (Biome)
+- **Indent**: 2 spaces | **Line endings**: LF
+- **Quotes**: Single `'` | **Semicolons**: Omit (ASI)
+- **Arrow parentheses**: Always `(x) => x`
+
+### Imports
+Biome auto-organizes. Order: 1) External packages → 2) Internal `@/*` aliases → 3) Type imports (`import type { ... }`)
+
+```typescript
+import { createFileRoute } from '@tanstack/react-router'
+import { z } from 'zod'
+import { db } from '@/server/db'
+import type { ReactNode } from 'react'
+```
+
+### TypeScript Strictness
+- `strict: true`, `noUncheckedIndexedAccess: true`, `noImplicitOverride: true`, `verbatimModuleSyntax: true`
+- Use `@/*` path aliases (maps to `src/*`)
+
+### Naming Conventions
+| Type | Convention | Example |
+|------|------------|---------|
+| Files (utils) | kebab-case | `auth-utils.ts` |
+| Files (components) | PascalCase | `UserProfile.tsx` |
+| Components | PascalCase arrow | `const Button = () => {}` |
+| Functions | camelCase | `getUserById` |
+| Constants | UPPER_SNAKE | `MAX_RETRIES` |
+| Types/Interfaces | PascalCase | `UserProfile` |
+
+### React Patterns
+- Components: arrow functions (enforced by Biome)
+- Routes: TanStack Router file conventions (`export const Route = createFileRoute(...)`)
+- Data fetching: `useSuspenseQuery(orpc.feature.list.queryOptions())`
+- Let React Compiler handle memoization (no manual `useMemo`/`useCallback`)
+
+### Error Handling
+- Use `try-catch` for async operations; throw descriptive errors
+- ORPC: Use `ORPCError` with proper codes (`NOT_FOUND`, `INPUT_VALIDATION_FAILED`)
+- Never use empty catch blocks
+
+## Database (Drizzle ORM)
+
+```typescript
+export const myTable = pgTable('my_table', {
+  id: uuid().primaryKey().default(sql`uuidv7()`),
+  name: text().notNull(),
+  createdAt: timestamp({ withTimezone: true }).notNull().defaultNow(),
+  updatedAt: timestamp({ withTimezone: true }).notNull().defaultNow().$onUpdateFn(() => new Date()),
+})
+```
+
+## Environment Variables
+
+- Use `@t3-oss/env-core` with Zod validation in `src/env.ts`
+- Server vars: no prefix | Client vars: `VITE_` prefix required
+- Never commit `.env` files
+
+## Dependency Management
+
+- All versions centralized in root `package.json` `catalog` field
+- Workspace packages use `"catalog:"` — never hardcode versions
+- Internal packages use `"workspace:*"` references
+
+## Critical Rules
+
+**DO:**
+- Run `bun fix` before committing
+- Use `@/*` path aliases (not relative imports)
+- Include `createdAt`/`updatedAt` on all tables
+- Use `catalog:` for dependency versions
+
+**DON'T:**
+- Use `npm`, `npx`, `node`, `yarn`, `pnpm` — always use `bun` / `bunx`
+- Edit `src/routeTree.gen.ts` (auto-generated)
+- Use `as any`, `@ts-ignore`, `@ts-expect-error`
+- Commit `.env` files
+- Use empty catch blocks `catch(e) {}`
+- Hardcode dependency versions in workspace packages
+
+## 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
+5. Commit with descriptive message
+
+## Directory Structure
+
+```
+.
+├── apps/
+│   ├── server/           # TanStack Start fullstack app
+│   │   ├── src/
+│   │   │   ├── client/   # ORPC client, Query client
+│   │   │   ├── components/
+│   │   │   ├── routes/   # File-based routing
+│   │   │   └── server/   # API layer + database
+│   │   │       ├── api/  # ORPC contracts, routers, middlewares
+│   │   │       └── db/   # Drizzle schema
+│   │   └── AGENTS.md
+│   └── desktop/          # Electrobun desktop shell
+│       ├── src/
+│       │   └── bun/
+│       │       └── index.ts       # Main process entry
+│       ├── electrobun.config.ts   # Electrobun configuration
+│       └── AGENTS.md
+├── packages/
+│   ├── tsconfig/         # Shared TS configs
+│   └── utils/            # Shared utilities
+├── biome.json            # Linting/formatting config
+├── turbo.json            # Turbo task orchestration
+└── package.json          # Workspace root + dependency catalog
+```
+
+## See Also
+
+- `apps/server/AGENTS.md` - Detailed TanStack Start / ORPC patterns
+- `apps/desktop/AGENTS.md` - Electrobun desktop development guide
--- a/apps/desktop/.gitignore
+++ b/apps/desktop/.gitignore
@@ -1,24 +1,3 @@
-# Logs
-logs
-*.log
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-pnpm-debug.log*
-lerna-debug.log*
-
-node_modules
-dist
-dist-ssr
-*.local
-
-# Editor directories and files
-.vscode/*
-!.vscode/extensions.json
-.idea
-.DS_Store
-*.suo
-*.ntvs*
-*.njsproj
-*.sln
-*.sw?
+# Electrobun build output
+build/
+artifacts/
--- a/apps/desktop/AGENTS.md
+++ b/apps/desktop/AGENTS.md
@@ -0,0 +1,131 @@
+# AGENTS.md - Desktop App Guidelines
+
+Thin Electrobun shell hosting the fullstack server app.
+
+## Tech Stack
+
+> **⚠️ This project uses Bun — NOT Node.js / npm. All commands use `bun`. Never use `npm`, `npx`, or `node`.**
+
+- **Type**: Electrobun desktop application
+- **Design**: Server-driven desktop (thin native shell hosting web app)
+- **Runtime**: Bun (Main process) + CEF (Chromium Embedded Framework)
+- **Framework**: Electrobun
+- **Build**: Electrobun CLI + Turborepo
+
+## Architecture
+
+- **Server-driven design**: The desktop app is a "thin" native shell. It does not contain UI or business logic; it merely hosts the `apps/server` TanStack Start application in a native window.
+- **Dev mode**: Connects to an external Vite dev server at `localhost:3000`. Requires `apps/server` to be running separately.
+- **Prod mode**: Spawns an embedded TanStack Start server (Nitro) as a child process and loads the dynamically assigned local URL.
+- **Config**: `electrobun.config.ts` manages app metadata (identifier, name), build entries, and asset bundling.
+
+## Commands
+
+```bash
+# Development
+bun dev                    # Start Electrobun dev mode (requires server dev running)
+
+# Build
+bun build                  # Build stable release (all platforms)
+
+# Code Quality
+bun fix                    # Biome auto-fix
+bun typecheck              # TypeScript check
+```
+
+## Directory Structure
+
+```
+.
+├── src/
+│   └── bun/
+│       └── index.ts       # Main process entry (Window management + server lifecycle)
+├── electrobun.config.ts   # App metadata and build/copy configuration
+├── package.json           # Scripts and dependencies
+├── turbo.json             # Build pipeline dependencies (depends on server build)
+└── AGENTS.md              # Desktop guidelines (this file)
+```
+
+## Development Workflow
+
+1. **Start server**: In `apps/server`, run `bun dev`.
+2. **Start desktop**: In `apps/desktop`, run `bun dev`.
+3. **Connection**: The desktop app polls `localhost:3000` until responsive, then opens the native window.
+
+## Production Architecture
+
+### Build Pipeline
+The desktop build is orchestrated by Turbo. It depends on the server's production build:
+- `turbo.json`: `@furtherverse/desktop#build` depends on `@furtherverse/server#build`.
+- `electrobun.config.ts`: Copies `../server/.output` to `server-output` folder within the app bundle.
+
+### Server Lifecycle
+In production, the main process manages the embedded server:
+- **Spawn**: Spawns server from `server-output/server/index.mjs` using `Bun.spawn`.
+- **Port Allocation**: A free port is pre-allocated via `node:net` (`createServer` on `127.0.0.1:0`), then passed to the server as the `PORT` environment variable.
+- **Readiness Check**: The main process polls the server URL with `fetch` until it responds, rather than parsing stdout.
+- **Retry**: If the server fails to become ready (timeout or early exit), the process is killed and a new attempt is made with a fresh port (up to 3 retries).
+- **Lifecycle**: The server process is tied to the app; it is killed on `SIGTERM`, `SIGINT`, or app exit. If the server process crashes, the app exits with an error.
+
+## Environment Detection
+
+The application determines its environment via the `ELECTROBUN_BUILD_ENV` variable, automatically set by the Electrobun CLI:
+
+```typescript
+const isDev = () => {
+  const env = process.env.ELECTROBUN_BUILD_ENV
+  return !env || env === 'dev'
+}
+```
+
+- **dev**: Development mode (connects to external host).
+- **canary / stable**: Production mode (starts embedded server).
+
+## Environment Variables
+
+- `ELECTROBUN_BUILD_ENV`: Auto-set by CLI. Determines whether to use local dev server or embedded server.
+- `DATABASE_URL`: Required by the server process. Must be passed through from the parent environment to the spawned child process.
+
+## Electrobun Patterns
+
+### BrowserWindow Configuration
+The main window uses the CEF renderer for consistency across platforms.
+
+```typescript
+new BrowserWindow({
+  title: 'Furtherverse',
+  url: serverUrl,
+  frame: {
+    x: 100,
+    y: 100,
+    width: 1200,
+    height: 800,
+  },
+  renderer: 'cef',
+})
+```
+
+### Path Aliases
+The main process uses `electrobun/bun` for native APIs and `PATHS` for locating bundled assets.
+
+```typescript
+import { BrowserWindow, PATHS } from 'electrobun/bun'
+
+// Locate the embedded server bundle
+const serverEntryPath = join(PATHS.VIEWS_FOLDER, '..', 'server-output', 'server', 'index.mjs')
+```
+
+## Critical Rules
+
+**DO:**
+- Use arrow functions for all components and utility functions.
+- Ensure `apps/server` is built before building `apps/desktop` (handled by Turbo).
+- Pre-allocate a free port and pass it via `PORT` env var instead of parsing stdout.
+- Handle server process termination to avoid orphan processes.
+- Use `catalog:` for all dependency versions in `package.json`.
+
+**DON'T:**
+- Use `npm`, `npx`, `node`, `yarn`, or `pnpm`. Always use `bun`.
+- Hardcode `localhost:3000` for production builds.
+- Include UI components or business logic in the desktop app (keep it thin).
+- Use `as any` or `@ts-ignore`.
--- a/apps/desktop/copy.ts
+++ b/apps/desktop/copy.ts
@@ -1,470 +0,0 @@
-import * as path from 'node:path'
-import { Schema } from '@effect/schema'
-import { $ } from 'bun'
-import { Console, Context, Data, Effect, Layer } from 'effect'
-
-// ============================================================================
-// Domain Models & Schema
-// ============================================================================
-
-/**
- * Bun 构建目标后缀
- */
-const BunTargetSuffixSchema = Schema.Literal(
-  'windows-x64',
-  'darwin-arm64',
-  'darwin-x64',
-  'linux-x64',
-  'linux-arm64',
-)
-
-/**
- * Tauri sidecar 目标三元组
- */
-const TauriTargetSchema = Schema.Literal(
-  'x86_64-pc-windows-msvc',
-  'aarch64-apple-darwin',
-  'x86_64-apple-darwin',
-  'x86_64-unknown-linux-gnu',
-  'aarch64-unknown-linux-gnu',
-)
-
-/**
- * 目标映射配置
- */
-const TargetMappingSchema = Schema.Struct({
-  bunSuffix: BunTargetSuffixSchema,
-  tauriTarget: TauriTargetSchema,
-})
-
-type TargetMapping = Schema.Schema.Type<typeof TargetMappingSchema>
-
-/**
- * 复制配置
- */
-const CopyConfigSchema = Schema.Struct({
-  sourceDir: Schema.String.pipe(Schema.nonEmptyString()),
-  targetDir: Schema.String.pipe(Schema.nonEmptyString()),
-  baseName: Schema.String.pipe(Schema.nonEmptyString()),
-  mappings: Schema.Array(TargetMappingSchema).pipe(Schema.minItems(1)),
-})
-
-type CopyConfig = Schema.Schema.Type<typeof CopyConfigSchema>
-
-/**
- * 复制结果
- */
-const CopyResultSchema = Schema.Struct({
-  bunSuffix: BunTargetSuffixSchema,
-  tauriTarget: TauriTargetSchema,
-  sourceFile: Schema.String,
-  targetFile: Schema.String,
-  success: Schema.Boolean,
-})
-
-type CopyResult = Schema.Schema.Type<typeof CopyResultSchema>
-
-// ============================================================================
-// Error Models
-// ============================================================================
-
-class ConfigError extends Data.TaggedError('ConfigError')<{
-  readonly message: string
-  readonly cause: unknown
-}> {}
-
-class FileSystemError extends Data.TaggedError('FileSystemError')<{
-  readonly operation: string
-  readonly path: string
-  readonly cause: unknown
-}> {}
-
-class CopyError extends Data.TaggedError('CopyError')<{
-  readonly source: string
-  readonly target: string
-  readonly cause: unknown
-}> {}
-
-// ============================================================================
-// Services
-// ============================================================================
-
-/**
- * 配置服务
- */
-class CopyConfigService extends Context.Tag('CopyConfigService')<
-  CopyConfigService,
-  CopyConfig
->() {
-  /**
-   * 从原始数据创建并验证配置
-   */
-  static fromRaw = (raw: unknown) =>
-    Effect.gen(function* () {
-      const decoded = yield* Schema.decodeUnknown(CopyConfigSchema)(raw)
-      return decoded
-    }).pipe(
-      Effect.catchAll((error) =>
-        Effect.fail(
-          new ConfigError({
-            message: '配置验证失败',
-            cause: error,
-          }),
-        ),
-      ),
-    )
-
-  /**
-   * 默认配置 Layer
-   */
-  static readonly Live = Layer.effect(
-    CopyConfigService,
-    CopyConfigService.fromRaw({
-      sourceDir: path.join(__dirname, '..', 'server', 'out'),
-      targetDir: path.join(__dirname, 'src-tauri', 'binaries'),
-      baseName: 'server',
-      mappings: [
-        {
-          bunSuffix: 'windows-x64',
-          tauriTarget: 'x86_64-pc-windows-msvc',
-        },
-        {
-          bunSuffix: 'darwin-arm64',
-          tauriTarget: 'aarch64-apple-darwin',
-        },
-        {
-          bunSuffix: 'darwin-x64',
-          tauriTarget: 'x86_64-apple-darwin',
-        },
-        {
-          bunSuffix: 'linux-x64',
-          tauriTarget: 'x86_64-unknown-linux-gnu',
-        },
-        {
-          bunSuffix: 'linux-arm64',
-          tauriTarget: 'aarch64-unknown-linux-gnu',
-        },
-      ],
-    } satisfies CopyConfig),
-  )
-}
-
-/**
- * 文件系统服务
- */
-class FileSystemService extends Context.Tag('FileSystemService')<
-  FileSystemService,
-  {
-    readonly ensureDir: (dir: string) => Effect.Effect<void, FileSystemError>
-    readonly fileExists: (
-      filePath: string,
-    ) => Effect.Effect<boolean, FileSystemError>
-    readonly dirExists: (
-      dirPath: string,
-    ) => Effect.Effect<boolean, FileSystemError>
-    readonly copyFile: (
-      source: string,
-      target: string,
-    ) => Effect.Effect<void, CopyError>
-  }
->() {
-  static readonly Live = Layer.succeed(FileSystemService, {
-    ensureDir: (dir: string) =>
-      Effect.tryPromise({
-        try: async () => {
-          await $`mkdir -p ${dir}`
-        },
-        catch: (cause: unknown) =>
-          new FileSystemError({
-            operation: 'ensureDir',
-            path: dir,
-            cause,
-          }),
-      }),
-
-    fileExists: (filePath: string) =>
-      Effect.tryPromise({
-        try: async () => {
-          const file = Bun.file(filePath)
-          return await file.exists()
-        },
-        catch: (cause: unknown) =>
-          new FileSystemError({
-            operation: 'fileExists',
-            path: filePath,
-            cause,
-          }),
-      }),
-
-    dirExists: (dirPath: string) =>
-      Effect.tryPromise({
-        try: async () => {
-          const { default: fs } = await import('node:fs/promises')
-          try {
-            const stat = await fs.stat(dirPath)
-            return stat.isDirectory()
-          } catch {
-            return false
-          }
-        },
-        catch: (cause: unknown) =>
-          new FileSystemError({
-            operation: 'dirExists',
-            path: dirPath,
-            cause,
-          }),
-      }),
-
-    copyFile: (source: string, target: string) =>
-      Effect.tryPromise({
-        try: async () => {
-          await $`cp ${source} ${target}`
-        },
-        catch: (cause: unknown) =>
-          new CopyError({
-            source,
-            target,
-            cause,
-          }),
-      }),
-  })
-}
-
-/**
- * 复制服务
- */
-class CopyService extends Context.Tag('CopyService')<
-  CopyService,
-  {
-    readonly copyBinary: (
-      config: CopyConfig,
-      mapping: TargetMapping,
-    ) => Effect.Effect<CopyResult, CopyError | FileSystemError>
-    readonly copyAllBinaries: (
-      config: CopyConfig,
-    ) => Effect.Effect<ReadonlyArray<CopyResult>, CopyError | FileSystemError>
-  }
->() {
-  static readonly Live = Layer.effect(
-    CopyService,
-    Effect.gen(function* () {
-      const fs = yield* FileSystemService
-
-      return {
-        copyBinary: (config: CopyConfig, mapping: TargetMapping) =>
-          Effect.gen(function* () {
-            const { sourceDir, targetDir, baseName } = config
-            const { bunSuffix, tauriTarget } = mapping
-
-            // 确定文件扩展名（Windows 需要 .exe）
-            const ext = tauriTarget.includes('windows') ? '.exe' : ''
-
-            // 构建源文件和目标文件路径
-            const sourceFile = path.join(
-              sourceDir,
-              `${baseName}-${bunSuffix}${ext}`,
-            )
-            const targetFile = path.join(
-              targetDir,
-              `${baseName}-${tauriTarget}${ext}`,
-            )
-
-            // 检查源文件是否存在
-            const exists = yield* fs.fileExists(sourceFile)
-            if (!exists) {
-              yield* Console.log(`⚠️  跳过 ${bunSuffix}: 源文件不存在`)
-              return {
-                bunSuffix,
-                tauriTarget,
-                sourceFile,
-                targetFile,
-                success: false,
-              } satisfies CopyResult
-            }
-
-            // 复制文件
-            yield* fs.copyFile(sourceFile, targetFile)
-
-            yield* Console.log(`✓ ${bunSuffix} → ${tauriTarget}`)
-            yield* Console.log(`  ${sourceFile}`)
-            yield* Console.log(`  → ${targetFile}\n`)
-
-            return {
-              bunSuffix,
-              tauriTarget,
-              sourceFile,
-              targetFile,
-              success: true,
-            } satisfies CopyResult
-          }),
-
-        copyAllBinaries: (config: CopyConfig) =>
-          Effect.gen(function* () {
-            const effects = config.mappings.map((mapping) =>
-              Effect.gen(function* () {
-                const { sourceDir, targetDir, baseName } = config
-                const { bunSuffix, tauriTarget } = mapping
-
-                const ext = tauriTarget.includes('windows') ? '.exe' : ''
-                const sourceFile = path.join(
-                  sourceDir,
-                  `${baseName}-${bunSuffix}${ext}`,
-                )
-                const targetFile = path.join(
-                  targetDir,
-                  `${baseName}-${tauriTarget}${ext}`,
-                )
-
-                const exists = yield* fs.fileExists(sourceFile)
-                if (!exists) {
-                  yield* Console.log(`⚠️  跳过 ${bunSuffix}: 源文件不存在`)
-                  return {
-                    bunSuffix,
-                    tauriTarget,
-                    sourceFile,
-                    targetFile,
-                    success: false,
-                  } satisfies CopyResult
-                }
-
-                yield* fs.copyFile(sourceFile, targetFile)
-
-                yield* Console.log(`✓ ${bunSuffix} → ${tauriTarget}`)
-                yield* Console.log(`  ${sourceFile}`)
-                yield* Console.log(`  → ${targetFile}\n`)
-
-                return {
-                  bunSuffix,
-                  tauriTarget,
-                  sourceFile,
-                  targetFile,
-                  success: true,
-                } satisfies CopyResult
-              }),
-            )
-
-            return yield* Effect.all(effects, { concurrency: 'unbounded' })
-          }),
-      }
-    }),
-  )
-}
-
-/**
- * 报告服务
- */
-class ReporterService extends Context.Tag('ReporterService')<
-  ReporterService,
-  {
-    readonly printSummary: (
-      results: ReadonlyArray<CopyResult>,
-    ) => Effect.Effect<void>
-  }
->() {
-  static readonly Live = Layer.succeed(ReporterService, {
-    printSummary: (results: ReadonlyArray<CopyResult>) =>
-      Effect.gen(function* () {
-        const successful = results.filter((r) => r.success)
-        const failed = results.filter((r) => !r.success)
-
-        yield* Console.log('\n📦 复制摘要:')
-        yield* Console.log(`  ✅ 成功: ${successful.length}`)
-        yield* Console.log(`  ⚠️  跳过: ${failed.length}`)
-
-        if (successful.length > 0) {
-          yield* Console.log('\n成功复制的文件:')
-          for (const result of successful) {
-            yield* Console.log(
-              `  • ${result.bunSuffix} → ${result.tauriTarget}`,
-            )
-          }
-        }
-
-        if (failed.length > 0) {
-          yield* Console.log('\n跳过的文件:')
-          for (const result of failed) {
-            yield* Console.log(`  • ${result.bunSuffix} (源文件不存在)`)
-          }
-        }
-      }),
-  })
-}
-
-// ============================================================================
-// Main Program
-// ============================================================================
-
-const program = Effect.gen(function* () {
-  const config = yield* CopyConfigService
-  const fs = yield* FileSystemService
-  const copier = yield* CopyService
-  const reporter = yield* ReporterService
-
-  yield* Console.log('📦 开始复制二进制文件到 Tauri sidecar 目录...\n')
-
-  // 1. 检查源目录
-  const sourceExists = yield* fs.dirExists(config.sourceDir)
-  if (!sourceExists) {
-    yield* Console.error(`❌ 源目录不存在: ${config.sourceDir}`)
-    yield* Console.log(
-      '💡 提示: 请先在 apps/server 中运行 bun run compile 构建服务器二进制文件',
-    )
-    return yield* Effect.fail(
-      new FileSystemError({
-        operation: 'checkSourceDir',
-        path: config.sourceDir,
-        cause: '源目录不存在',
-      }),
-    )
-  }
-
-  // 2. 创建目标目录
-  yield* fs.ensureDir(config.targetDir)
-  yield* Console.log(`✓ 目标目录: ${config.targetDir}\n`)
-
-  // 3. 并行复制所有二进制文件
-  const results = yield* copier.copyAllBinaries(config)
-
-  // 4. 输出摘要
-  yield* reporter.printSummary(results)
-
-  return results
-})
-
-// ============================================================================
-// Layer Composition
-// ============================================================================
-
-const MainLayer = Layer.mergeAll(
-  CopyConfigService.Live,
-  FileSystemService.Live,
-  CopyService.Live.pipe(Layer.provide(FileSystemService.Live)),
-  ReporterService.Live,
-)
-
-// ============================================================================
-// Runner
-// ============================================================================
-
-const runnable = program.pipe(
-  Effect.provide(MainLayer),
-  Effect.catchTags({
-    ConfigError: (error) =>
-      Console.error(`❌ 配置错误: ${error.message}`, error.cause),
-    FileSystemError: (error) =>
-      Console.error(
-        `❌ 文件系统错误 [${error.operation}]: ${error.path}`,
-        error.cause,
-      ),
-    CopyError: (error) =>
-      Console.error(
-        `❌ 复制失败: ${error.source} → ${error.target}`,
-        error.cause,
-      ),
-  }),
-  Effect.tapErrorCause((cause) => Console.error('❌ 未预期的错误:', cause)),
-)
-
-Effect.runPromise(runnable).catch(() => {
-  process.exit(1)
-})
--- a/apps/desktop/electrobun.config.ts
+++ b/apps/desktop/electrobun.config.ts
@@ -0,0 +1,27 @@
+import type { ElectrobunConfig } from 'electrobun'
+
+export default {
+  app: {
+    name: 'Desktop',
+    identifier: 'com.furtherverse.desktop',
+    version: '1.0.0',
+  },
+  build: {
+    bun: {
+      entrypoint: 'src/bun/index.ts',
+    },
+    copy: {
+      '../server/.output': 'server-output',
+    },
+    targets: 'win-x64',
+    linux: {
+      bundleCEF: true,
+    },
+    mac: {
+      bundleCEF: false,
+    },
+    win: {
+      bundleCEF: false,
+    },
+  },
+} satisfies ElectrobunConfig
--- a/apps/desktop/package.json
+++ b/apps/desktop/package.json
@@ -4,16 +4,16 @@
  "private": true,
  "type": "module",
  "scripts": {
-    "build": "bun run copy && tauri build",
-    "copy": "rm -rf binaries && bun --bun copy.ts",
-    "dev": "bun run copy && tauri dev"
+    "build": "electrobun build --env=stable",
+    "dev": "electrobun build && electrobun dev",
+    "fix": "biome check --write",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "electrobun": "catalog:"
  },
  "devDependencies": {
-    "@effect/schema": "catalog:",
    "@furtherverse/tsconfig": "workspace:*",
-    "@tauri-apps/cli": "catalog:",
-    "@types/bun": "catalog:",
-    "effect": "catalog:",
-    "typescript": "catalog:"
+    "@types/bun": "catalog:"
  }
 }
--- a/apps/desktop/src-tauri/.gitignore
+++ b/apps/desktop/src-tauri/.gitignore
@@ -1,10 +0,0 @@
-# Generated by Cargo
-# will have compiled files and executables
-/target/
-
-# Generated by Tauri
-# will have schema files for capabilities auto-completion
-/gen/schemas
-
-# Tauri Sidecar
-binaries/
--- a/apps/desktop/src-tauri/AGENTS.md
+++ b/apps/desktop/src-tauri/AGENTS.md
@@ -1,357 +0,0 @@
-# AGENTS.md - Tauri Shell 项目开发指南
-
-本文档为 AI 编程助手和开发者提供项目规范、构建命令和代码风格指南。
-
-## 项目概览
-
- **项目类型**: Tauri v2 桌面应用（轻量级壳子）
- **后端**: Rust (Edition 2021)
- **架构**: Sidecar 模式 - Sidecar App 承载主要业务逻辑
- **设计理念**: Tauri 仅提供原生桌面能力（文件对话框、系统通知等），Web 逻辑全部由 Sidecar App 处理
- **开发模式**: 使用 localhost:3000（需手动启动开发服务器）
- **生产模式**: 自动启动 Sidecar 二进制
- **异步运行时**: Tokio
- **Rust 版本**: 1.92.0+
- **工具管理**: 使用 mise 管理 Rust 和 Tauri CLI 版本（见 `mise.toml`）
-
-## 构建、测试、运行命令
-
-### 开发运行
-```bash
-# 开发模式运行 (需要先启动开发服务器)
-# 终端 1: 启动前端开发服务器
-bun run dev
-
-# 终端 2: 启动 Tauri 应用
-tauri dev
-
-# 或者使用单命令并行启动（需要配置 package.json）
-bun run dev:tauri
-```
-
-**开发模式说明**：
- 开发模式下，Tauri 直接连接到 `localhost:3000`（不启动 sidecar 二进制）
- 需要手动运行 `bun run dev` 来启动开发服务器
- 支持热重载（HMR），无需重启 Tauri 应用
-
-### 构建
-```bash
-# 开发构建 (debug mode)
-cargo build
-
-# 生产构建
-cargo build --release
-
-# Tauri 应用打包 (生成安装程序)
-tauri build
-```
-
-### 代码检查
-```bash
-# 编译检查 (不生成二进制)
-cargo check
-
-# Clippy 代码质量检查
-cargo clippy
-
-# Clippy 严格模式 (所有警告视为错误)
-cargo clippy -- -D warnings
-
-# 代码格式化检查
-cargo fmt -- --check
-
-# 自动格式化代码
-cargo fmt
-```
-
-### 测试
-```bash
-# 运行所有测试
-cargo test
-
-# 运行单个测试 (按名称过滤)
-cargo test test_function_name
-
-# 运行特定模块的测试
-cargo test module_name::
-
-# 显示测试输出 (包括 println!)
-cargo test -- --nocapture
-
-# 运行单个测试并显示输出
-cargo test test_name -- --nocapture
-```
-
-### 清理
-```bash
-# 清理构建产物
-cargo clean
-```
-
-## 项目结构
-
-```
-server-desktop/
-├── src/
-│   ├── main.rs          # 入口文件 (仅调用 lib::run)
-│   ├── lib.rs           # 核心应用逻辑 (注册插件、命令、状态)
-│   ├── commands/
-│   │   └── mod.rs       # 原生桌面功能命令 (文件对话框、通知等)
-│   └── sidecar.rs       # Sidecar 进程管理 (启动、端口扫描、清理)
-├── binaries/            # Sidecar 二进制文件
-│   └── app-*   # Sidecar App 可执行文件 (示例: app)
-├── capabilities/        # Tauri v2 权限配置
-│   └── default.json
-├── icons/               # 应用图标资源
-├── gen/schemas/         # 自动生成的 Schema (不要手动编辑)
-├── Cargo.toml          # Rust 项目配置
-├── tauri.conf.json     # Tauri 应用配置
-├── build.rs            # Rust 构建脚本
-└── mise.toml           # 开发工具版本管理
-```
-
-## Rust 代码风格指南
-
-### 导入 (Imports)
-
- 使用标准库、外部 crate、当前 crate 的顺序，用空行分隔
- 按字母顺序排列
- 优先使用具体导入而非通配符 `*`
-
-```rust
-// ✅ 推荐
-use std::sync::Mutex;
-use std::time::Duration;
-
-use tauri::Manager;
-use tauri_plugin_shell::ShellExt;
-use tauri_plugin_shell::process::{CommandEvent, CommandChild};
-
-// ❌ 避免
-use tauri::*;
-```
-
-### 命名规范
-
- **函数和变量**: `snake_case`
- **类型、结构体、枚举、Trait**: `PascalCase`
- **常量和静态变量**: `SCREAMING_SNAKE_CASE`
- **生命周期参数**: 简短小写字母，如 `'a`, `'b`
-
-```rust
-// ✅ 推荐
-struct SidecarProcess(Mutex<Option<CommandChild>>);
-const DEFAULT_PORT: u16 = 3000;
-async fn find_available_port(start: u16) -> u16 { }
-
-// ❌ 避免
-struct sidecar_process { }
-const defaultPort: u16 = 3000;
-```
-
-### 类型注解
-
- 函数参数必须有类型注解
- 函数返回值必须明确声明 (除非返回 `()`)
- 优先使用具体类型而非 `impl Trait` (除非必要)
- 使用 `&str` 而非 `String` 作为只读字符串参数
-
-```rust
-// ✅ 推荐
-#[tauri::command]
-fn greet(name: &str) -> String {
-    format!("Hello, {}!", name)
-}
-
-async fn is_port_available(port: u16) -> bool {
-    tokio::net::TcpListener::bind(format!("127.0.0.1:{}", port))
-        .await
-        .is_ok()
-}
-```
-
-### 错误处理
-
- 使用 `Result<T, E>` 返回可能失败的操作
- 使用 `expect()` 时提供有意义的错误消息 (中文)
- 避免 `unwrap()` 在生产代码中，除非逻辑上保证不会 panic
- 使用 `?` 操作符传播错误
- 记录关键错误信息到控制台
-
-```rust
-// ✅ 推荐
-let sidecar = app_handle
-    .shell()
-    .sidecar("app")
-    .expect("无法找到 app sidecar");
-
-let (mut rx, child) = sidecar.spawn().expect("启动 sidecar 失败");
-
-// 日志记录
-eprintln!("✗ Sidecar App 启动失败");
-println!("✓ Sidecar App 启动成功！");
-
-// ❌ 避免
-let data = read_file().unwrap();  // 无上下文信息
-```
-
-### 异步代码
-
- 使用 `async/await` 而非手动创建 Future
- Tauri 内部使用 `tauri::async_runtime::spawn` 启动异步任务
- 使用 Tokio 的异步 API (如 `tokio::net::TcpListener`)
- 避免阻塞异步运行时 (使用 `tokio::task::spawn_blocking`)
-
-```rust
-// ✅ 推荐
-tauri::async_runtime::spawn(async move {
-    let port = find_available_port(3000).await;
-    // ...
-});
-```
-
-### 格式化
-
- 使用 `cargo fmt` 自动格式化
- 缩进: 4 空格
- 行宽: 100 字符 (rustfmt 默认)
- 结构体和枚举的字段每行一个 (如果超过一定长度)
- 链式调用适当换行提高可读性
-
-### 注释
-
- 使用中文注释说明复杂逻辑
- 代码块前添加简短说明注释
- 避免显而易见的注释
-
-```rust
-// ✅ 推荐
-// 全局状态：存储 Sidecar App 进程句柄
-struct SidecarProcess(Mutex<Option<CommandChild>>);
-
-// 检查端口是否可用
-async fn is_port_available(port: u16) -> bool { }
-```
-
-## Tauri 特定规范
-
-### 模块组织
-
- **`lib.rs`**: 主入口，负责注册插件、命令、状态管理
- **`commands/mod.rs`**: 所有 Tauri 命令集中定义，命令必须是 `pub fn`
- **`sidecar.rs`**: Sidecar 进程管理逻辑，导出公共 API（`spawn_sidecar`, `cleanup_sidecar_process`）
-
-```rust
-// lib.rs - 模块声明
-mod commands;
-mod sidecar;
-
-use sidecar::SidecarProcess;
-
-// 注册命令时使用模块路径
-.invoke_handler(tauri::generate_handler![commands::greet])
-```
-
-### 命令定义
-
- 使用 `#[tauri::command]` 宏标记命令
- 命令函数必须是公开的或在 `invoke_handler` 中注册
- 参数类型必须实现 `serde::Deserialize`
- 返回类型必须实现 `serde::Serialize`
-
-```rust
-#[tauri::command]
-fn greet(name: &str) -> String {
-    format!("Hello, {}!", name)
-}
-
-// 在 Builder 中注册
-.invoke_handler(tauri::generate_handler![greet])
-```
-
-### 状态管理
-
- 使用 `app.manage()` 注册全局状态
- 状态必须实现 `Send + Sync`
- 使用 `Mutex` 或 `RwLock` 保证线程安全
-
-```rust
-struct SidecarProcess(Mutex<Option<CommandChild>>);
-
-// 注册状态
-app.manage(SidecarProcess(Mutex::new(None)));
-
-// 访问状态
-if let Some(state) = app_handle.try_state::<SidecarProcess>() {
-    *state.0.lock().unwrap() = Some(child);
-}
-```
-
-### Sidecar 进程管理
-
- Sidecar 二进制必须在 `tauri.conf.json` 的 `bundle.externalBin` 中声明
- 使用 `app.shell().sidecar()` 启动 sidecar
- 在应用退出时清理子进程 (监听 `RunEvent::ExitRequested`)
-
-```rust
-// 启动 sidecar
-let sidecar = app_handle
-    .shell()
-    .sidecar("app")
-    .expect("无法找到 app sidecar")
-    .env("PORT", port.to_string());
-
-// 清理进程
-match event {
-    tauri::RunEvent::ExitRequested { .. } | tauri::RunEvent::Exit => {
-        if let Some(child) = process.take() {
-            let _ = child.kill();
-        }
-    }
-    _ => {}
-}
-```
-
-## 依赖管理
-
- 在 `Cargo.toml` 中明确声明依赖版本
- 使用语义化版本 (如 `"2"` 表示兼容 2.x.x)
- 仅启用需要的 feature 以减少编译时间和二进制大小
-
-```toml
-tauri = { version = "2", features = [] }
-tauri-plugin-opener = "2"
-tauri-plugin-shell = "2"
-serde = { version = "1", features = ["derive"] }
-tokio = { version = "1", features = ["net"] }
-```
-
-## 开发工具
-
-推荐安装以下 VSCode 扩展:
- `tauri-apps.tauri-vscode` - Tauri 官方支持
- `rust-lang.rust-analyzer` - Rust 语言服务器
-
-## 最佳实践
-
-1. **开发环境配置**: 
-   - 开发模式下需先启动前端开发服务器（`bun run dev`），再启动 Tauri（`tauri dev`）
-   - 生产构建自动打包 sidecar 二进制，无需额外配置
-2. **进程生命周期**: 始终在应用退出时清理子进程和资源
-3. **端口管理**: 
-   - 开发模式固定使用 3000 端口（与开发服务器匹配）
-   - 生产模式使用端口扫描避免硬编码端口冲突
-4. **超时处理**: 异步操作设置合理的超时时间 (如 5 秒)
-5. **日志**: 使用表情符号 (✓/✗/🔧/🚀) 和中文消息提供清晰的状态反馈
-6. **错误退出**: 关键错误时调用 `std::process::exit(1)`
-7. **窗口配置**: 使用 `WebviewWindowBuilder` 动态创建窗口
-
-## 提交代码前检查清单
-
- [ ] `cargo fmt` 格式化通过
- [ ] `cargo clippy` 无警告
- [ ] `cargo check` 编译通过
- [ ] `cargo test` 测试通过
- [ ] 更新相关注释和文档
- [ ] 检查是否有 `unwrap()` 需要替换为 `expect()`
- [ ] 验证 Tauri 应用正常启动和退出
--- a/apps/desktop/src-tauri/Cargo.lock
+++ b/apps/desktop/src-tauri/Cargo.lock
--- a/apps/desktop/src-tauri/Cargo.toml
+++ b/apps/desktop/src-tauri/Cargo.toml
@@ -1,24 +0,0 @@
-[package]
-name = "server-desktop"
-version = "0.1.0"
-description = "A Tauri App"
-authors = ["imbytecat"]
-edition = "2021"
-
-# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
-
-[lib]
-# The `_lib` suffix may seem redundant but it is necessary
-# to make the lib name unique and wouldn't conflict with the bin name.
-# This seems to be only an issue on Windows, see https://github.com/rust-lang/cargo/issues/8519
-name = "server_desktop_lib"
-crate-type = ["staticlib", "cdylib", "rlib"]
-
-[build-dependencies]
-tauri-build = { version = "2", features = [] }
-
-[dependencies]
-tauri = { version = "2", features = [] }
-tauri-plugin-shell = "2"
-serde = { version = "1", features = ["derive"] }
-tokio = { version = "1", features = ["net"] }
--- a/apps/desktop/src-tauri/build.rs
+++ b/apps/desktop/src-tauri/build.rs
@@ -1,3 +0,0 @@
-fn main() {
-    tauri_build::build()
-}
--- a/apps/desktop/src-tauri/capabilities/default.json
+++ b/apps/desktop/src-tauri/capabilities/default.json
@@ -1,27 +0,0 @@
-{
-  "$schema": "../gen/schemas/desktop-schema.json",
-  "identifier": "default",
-  "description": "Capability for the main window",
-  "windows": ["main"],
-  "local": true,
-  "remote": {
-    "urls": [
-      "http://localhost:*",
-      "http://127.0.0.1:*",
-      "http{s}?://localhost(:\\d+)?/*"
-    ]
-  },
-  "permissions": [
-    "core:default",
-    "core:window:allow-set-title",
-    {
-      "identifier": "shell:allow-execute",
-      "allow": [
-        {
-          "name": "binaries/app",
-          "sidecar": true
-        }
-      ]
-    }
-  ]
-}
--- a/apps/desktop/src-tauri/icons/128x128.png
+++ b/apps/desktop/src-tauri/icons/128x128.png
--- a/apps/desktop/src-tauri/icons/128x128@2x.png
+++ b/apps/desktop/src-tauri/icons/128x128@2x.png
--- a/apps/desktop/src-tauri/icons/32x32.png
+++ b/apps/desktop/src-tauri/icons/32x32.png
--- a/apps/desktop/src-tauri/icons/Square107x107Logo.png
+++ b/apps/desktop/src-tauri/icons/Square107x107Logo.png
--- a/apps/desktop/src-tauri/icons/Square142x142Logo.png
+++ b/apps/desktop/src-tauri/icons/Square142x142Logo.png
--- a/apps/desktop/src-tauri/icons/Square150x150Logo.png
+++ b/apps/desktop/src-tauri/icons/Square150x150Logo.png
--- a/apps/desktop/src-tauri/icons/Square284x284Logo.png
+++ b/apps/desktop/src-tauri/icons/Square284x284Logo.png
--- a/apps/desktop/src-tauri/icons/Square30x30Logo.png
+++ b/apps/desktop/src-tauri/icons/Square30x30Logo.png
--- a/apps/desktop/src-tauri/icons/Square310x310Logo.png
+++ b/apps/desktop/src-tauri/icons/Square310x310Logo.png
--- a/apps/desktop/src-tauri/icons/Square44x44Logo.png
+++ b/apps/desktop/src-tauri/icons/Square44x44Logo.png
--- a/apps/desktop/src-tauri/icons/Square71x71Logo.png
+++ b/apps/desktop/src-tauri/icons/Square71x71Logo.png
--- a/apps/desktop/src-tauri/icons/Square89x89Logo.png
+++ b/apps/desktop/src-tauri/icons/Square89x89Logo.png
--- a/apps/desktop/src-tauri/icons/StoreLogo.png
+++ b/apps/desktop/src-tauri/icons/StoreLogo.png
--- a/apps/desktop/src-tauri/icons/icon.icns
+++ b/apps/desktop/src-tauri/icons/icon.icns
--- a/apps/desktop/src-tauri/icons/icon.ico
+++ b/apps/desktop/src-tauri/icons/icon.ico
--- a/apps/desktop/src-tauri/icons/icon.png
+++ b/apps/desktop/src-tauri/icons/icon.png
--- a/apps/desktop/src-tauri/src/commands/mod.rs
+++ b/apps/desktop/src-tauri/src/commands/mod.rs
@@ -1,8 +0,0 @@
-// 原生桌面功能命令
-// 未来可能包含: 文件对话框、系统通知、剪贴板等
-
-// 示例命令 (可根据需要删除或替换)
-#[tauri::command]
-pub fn greet(name: &str) -> String {
-    format!("Hello, {}! You've been greeted from Rust!", name)
-}
--- a/apps/desktop/src-tauri/src/lib.rs
+++ b/apps/desktop/src-tauri/src/lib.rs
@@ -1,33 +0,0 @@
-use tauri::Manager;
-
-// 模块声明
-mod commands;
-mod sidecar;
-
-use sidecar::SidecarProcess;
-
-#[cfg_attr(mobile, tauri::mobile_entry_point)]
-pub fn run() {
-    tauri::Builder::default()
-        .plugin(tauri_plugin_shell::init())
-        .setup(|app| {
-            // 注册全局状态
-            app.manage(SidecarProcess(std::sync::Mutex::new(None)));
-
-            // 启动 Sidecar 进程
-            let app_handle = app.handle().clone();
-            sidecar::spawn_sidecar(app_handle);
-
-            Ok(())
-        })
-        .invoke_handler(tauri::generate_handler![commands::greet])
-        .build(tauri::generate_context!())
-        .expect("error while building tauri application")
-        .run(|app_handle, event| {
-            // 监听应用退出事件，清理 Sidecar 进程
-            if let tauri::RunEvent::Exit = event {
-                // 只在 Exit 事件时清理，避免重复执行
-                sidecar::cleanup_sidecar_process(app_handle);
-            }
-        });
-}
--- a/apps/desktop/src-tauri/src/main.rs
+++ b/apps/desktop/src-tauri/src/main.rs
@@ -1,6 +0,0 @@
-// Prevents additional console window on Windows in release, DO NOT REMOVE!!
-#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
-
-fn main() {
-    server_desktop_lib::run()
-}
--- a/apps/desktop/src-tauri/src/sidecar.rs
+++ b/apps/desktop/src-tauri/src/sidecar.rs
@@ -1,166 +0,0 @@
-use std::sync::Mutex;
-use std::time::Duration;
-
-use tauri::Manager;
-use tauri_plugin_shell::process::{CommandChild, CommandEvent};
-use tauri_plugin_shell::ShellExt;
-
-// ===== 配置常量 =====
-
-/// Sidecar App 启动超时时间（秒）
-const STARTUP_TIMEOUT_SECS: u64 = 5;
-
-/// 默认起始端口
-const DEFAULT_PORT: u16 = 3000;
-
-/// 端口扫描范围（从起始端口开始扫描的端口数量）
-const PORT_SCAN_RANGE: u16 = 100;
-
-/// 窗口默认宽度
-const DEFAULT_WINDOW_WIDTH: f64 = 1200.0;
-
-/// 窗口默认高度
-const DEFAULT_WINDOW_HEIGHT: f64 = 800.0;
-
-/// 窗口标题
-const WINDOW_TITLE: &str = "Tauri App";
-
-// ===== 数据结构 =====
-
-/// 全局状态：存储 Sidecar 进程句柄
-pub struct SidecarProcess(pub Mutex<Option<CommandChild>>);
-
-// 检查端口是否可用（未被占用）
-async fn is_port_available(port: u16) -> bool {
-    tokio::net::TcpListener::bind(format!("127.0.0.1:{}", port))
-        .await
-        .is_ok()
-}
-
-// 查找可用端口
-async fn find_available_port(start: u16) -> u16 {
-    for port in start..start + PORT_SCAN_RANGE {
-        if is_port_available(port).await {
-            return port;
-        }
-    }
-    start // 回退到起始端口
-}
-
-/// 启动 Sidecar 进程并创建主窗口
-pub fn spawn_sidecar(app_handle: tauri::AppHandle) {
-    // 检测是否为开发模式
-    let is_dev = cfg!(debug_assertions);
-
-    if is_dev {
-        // 开发模式：直接创建窗口连接到 Vite 开发服务器
-        println!("🔧 开发模式");
-
-        match tauri::WebviewWindowBuilder::new(
-            &app_handle,
-            "main",
-            tauri::WebviewUrl::External("http://localhost:3000".parse().unwrap()),
-        )
-        .title(WINDOW_TITLE)
-        .inner_size(DEFAULT_WINDOW_WIDTH, DEFAULT_WINDOW_HEIGHT)
-        .center()
-        .build()
-        {
-            Ok(_) => println!("✓ 开发窗口创建成功"),
-            Err(e) => {
-                eprintln!("✗ 窗口创建失败: {}", e);
-            }
-        }
-
-        return;
-    }
-
-    // 生产模式：启动 sidecar 二进制
-    tauri::async_runtime::spawn(async move {
-        println!("🚀 生产模式");
-
-        // 查找可用端口
-        let port = find_available_port(DEFAULT_PORT).await;
-        println!("使用端口: {}", port);
-
-        // 启动 sidecar
-        let sidecar = app_handle
-            .shell()
-            .sidecar("server")
-            .expect("无法找到 app")
-            .env("PORT", port.to_string());
-
-        let (mut rx, child) = sidecar.spawn().expect("启动 sidecar 失败");
-
-        // 保存进程句柄到全局状态
-        if let Some(state) = app_handle.try_state::<SidecarProcess>() {
-            *state.0.lock().unwrap() = Some(child);
-        }
-
-        // 监听 stdout，等待服务器就绪信号
-        let start_time = std::time::Instant::now();
-        let timeout = Duration::from_secs(STARTUP_TIMEOUT_SECS);
-        let mut app_ready = false;
-
-        while let Some(event) = rx.recv().await {
-            if let CommandEvent::Stdout(line) = event {
-                let output = String::from_utf8_lossy(&line);
-                println!("App: {}", output);
-
-                // 检测 App 启动成功的标志
-                if output.contains("Listening on:") || output.contains("localhost") {
-                    app_ready = true;
-                    println!("✓ App 启动成功！");
-
-                    // 创建主窗口
-                    let url = format!("http://localhost:{}", port);
-                    tauri::WebviewWindowBuilder::new(
-                        &app_handle,
-                        "main",
-                        tauri::WebviewUrl::External(url.parse().unwrap()),
-                    )
-                    .title(WINDOW_TITLE)
-                    .inner_size(DEFAULT_WINDOW_WIDTH, DEFAULT_WINDOW_HEIGHT)
-                    .center()
-                    .build()
-                    .expect("创建窗口失败");
-
-                    break;
-                }
-            }
-
-            // 超时检查
-            if start_time.elapsed() > timeout {
-                eprintln!("✗ 启动超时: App 未能在 {} 秒内启动", STARTUP_TIMEOUT_SECS);
-                break;
-            }
-        }
-
-        if !app_ready {
-            eprintln!("✗ App 启动失败");
-            std::process::exit(1);
-        }
-    });
-}
-
-/// 清理 Sidecar 进程 (在应用退出时调用)
-pub fn cleanup_sidecar_process(app_handle: &tauri::AppHandle) {
-    let is_dev = cfg!(debug_assertions);
-
-    if is_dev {
-        // 开发模式：退出时发送异常信号（exit 1），让 Turbo 停止 Vite 服务器
-        println!("🔧 开发模式退出，终止所有依赖任务...");
-        std::process::exit(1);
-    }
-
-    // 生产模式：正常清理 sidecar 进程
-    println!("应用退出，正在清理 Sidecar 进程...");
-    if let Some(state) = app_handle.try_state::<SidecarProcess>() {
-        if let Ok(mut process) = state.0.lock() {
-            if let Some(child) = process.take() {
-                let _ = child.kill();
-                println!("✓ Sidecar 进程已终止");
-            }
-        }
-    }
-}
--- a/apps/desktop/src-tauri/tauri.conf.json
+++ b/apps/desktop/src-tauri/tauri.conf.json
@@ -1,25 +0,0 @@
-{
-  "$schema": "https://schema.tauri.app/config/2",
-  "productName": "server-desktop",
-  "version": "0.1.0",
-  "identifier": "com.imbytecat.server-desktop",
-  "app": {
-    "withGlobalTauri": true,
-    "windows": [],
-    "security": {
-      "csp": null
-    }
-  },
-  "bundle": {
-    "active": true,
-    "targets": "all",
-    "icon": [
-      "icons/32x32.png",
-      "icons/128x128.png",
-      "icons/128x128@2x.png",
-      "icons/icon.icns",
-      "icons/icon.ico"
-    ],
-    "externalBin": ["binaries/server"]
-  }
-}
--- a/apps/desktop/src/bun/index.ts
+++ b/apps/desktop/src/bun/index.ts
@@ -0,0 +1,166 @@
+import { createServer } from 'node:net'
+import { dirname, join } from 'node:path'
+import { BrowserWindow, PATHS } from 'electrobun/bun'
+
+const DEV_SERVER_URL = 'http://localhost:3000'
+const SERVER_READY_TIMEOUT_MS = 5_000
+const MAX_SPAWN_RETRIES = 3
+
+const isDev = (): boolean => {
+  const env = process.env.ELECTROBUN_BUILD_ENV
+  return !env || env === 'dev'
+}
+
+const getServerEntryPath = (): string => {
+  return join(PATHS.VIEWS_FOLDER, '..', 'server-output', 'server', 'index.mjs')
+}
+
+const getFreePort = (): Promise<number> => {
+  return new Promise((resolve, reject) => {
+    const srv = createServer()
+    srv.unref()
+    srv.once('error', reject)
+    srv.listen({ port: 0, host: '127.0.0.1', exclusive: true }, () => {
+      const addr = srv.address()
+      if (addr && typeof addr === 'object') {
+        const port = addr.port
+        srv.close((err) => (err ? reject(err) : resolve(port)))
+      } else {
+        srv.close(() => reject(new Error('Unexpected address() result')))
+      }
+    })
+  })
+}
+
+const waitForServer = async (
+  url: string,
+  timeoutMs = SERVER_READY_TIMEOUT_MS,
+): Promise<boolean> => {
+  const start = Date.now()
+  while (Date.now() - start < timeoutMs) {
+    try {
+      const response = await fetch(url, { method: 'HEAD' })
+      if (response.ok) return true
+    } catch (_) {
+      // Server not up yet, retry after sleep
+    }
+    await Bun.sleep(100)
+  }
+  return false
+}
+
+const spawnServer = async (): Promise<{
+  process: ReturnType<typeof Bun.spawn>
+  url: string
+}> => {
+  const serverEntryPath = getServerEntryPath()
+  const serverDir = dirname(serverEntryPath)
+
+  for (let attempt = 1; attempt <= MAX_SPAWN_RETRIES; attempt++) {
+    const port = await getFreePort()
+    const url = `http://127.0.0.1:${port}`
+
+    const serverProc = Bun.spawn([process.execPath, serverEntryPath], {
+      cwd: serverDir,
+      env: {
+        ...process.env,
+        PORT: String(port),
+        HOST: '127.0.0.1',
+      },
+      stdio: ['ignore', 'inherit', 'inherit'],
+    })
+
+    const ready = await Promise.race([
+      waitForServer(url),
+      serverProc.exited.then((code) => {
+        throw new Error(`Server exited with code ${code} before becoming ready`)
+      }),
+    ])
+
+    if (ready) {
+      return { process: serverProc, url }
+    }
+
+    serverProc.kill()
+    await serverProc.exited
+    console.warn(
+      `Server failed to become ready on port ${port} (attempt ${attempt}/${MAX_SPAWN_RETRIES})`,
+    )
+  }
+
+  throw new Error(`Server failed to start after ${MAX_SPAWN_RETRIES} attempts`)
+}
+
+const main = async () => {
+  console.log('Starting Furtherverse Desktop...')
+
+  let serverUrl: string
+  let serverProcess: ReturnType<typeof Bun.spawn> | null = null
+
+  if (isDev()) {
+    console.log('Dev mode: waiting for external server at', DEV_SERVER_URL)
+    const ready = await waitForServer(DEV_SERVER_URL)
+    if (!ready) {
+      console.error(
+        'Dev server not responding. Make sure to run: bun dev in apps/server',
+      )
+      process.exit(1)
+    }
+    console.log('Dev server ready!')
+    serverUrl = DEV_SERVER_URL
+  } else {
+    console.log('Production mode: starting embedded server...')
+    try {
+      const server = await spawnServer()
+      serverProcess = server.process
+      serverUrl = server.url
+      console.log('Server ready at', serverUrl)
+    } catch (err) {
+      console.error('Failed to start embedded server:', err)
+      process.exit(1)
+    }
+  }
+
+  new BrowserWindow({
+    title: 'Furtherverse',
+    url: serverUrl,
+    frame: {
+      x: 100,
+      y: 100,
+      width: 1200,
+      height: 800,
+    },
+    renderer: 'cef',
+  })
+
+  if (serverProcess) {
+    const cleanup = () => {
+      if (serverProcess) {
+        serverProcess.kill()
+        serverProcess = null
+      }
+    }
+
+    process.on('exit', cleanup)
+    process.on('SIGTERM', () => {
+      cleanup()
+      process.exit(0)
+    })
+    process.on('SIGINT', () => {
+      cleanup()
+      process.exit(0)
+    })
+
+    serverProcess.exited.then((code) => {
+      if (serverProcess) {
+        console.error(`Server exited unexpectedly with code ${code}`)
+        process.exit(1)
+      }
+    })
+  }
+}
+
+main().catch((error) => {
+  console.error('Failed to start:', error)
+  process.exit(1)
+})
--- a/apps/desktop/tsconfig.json
+++ b/apps/desktop/tsconfig.json
@@ -1,4 +1,6 @@
 {
  "extends": "@furtherverse/tsconfig/bun.json",
-  "exclude": ["node_modules", "src-tauri"]
+  "compilerOptions": {
+    "lib": ["ESNext", "DOM", "DOM.Iterable"]
+  }
 }
--- a/apps/desktop/turbo.json
+++ b/apps/desktop/turbo.json
@@ -3,12 +3,8 @@
  "extends": ["//"],
  "tasks": {
    "build": {
-      "dependsOn": ["@furtherverse/server#compile"],
-      "outputs": ["src-tauri/target/release/**"]
-    },
-    "dev": {
-      "dependsOn": ["@furtherverse/server#compile"],
-      "with": ["@furtherverse/server#dev"]
+      "dependsOn": ["@furtherverse/server#build"],
+      "outputs": ["build/**", "artifacts/**"]
    }
  }
 }
--- a/apps/server/AGENTS.md
+++ b/apps/server/AGENTS.md
@@ -1,155 +1,124 @@
-# AGENTS.md - AI Coding Agent Guidelines
+# AGENTS.md - Server App Guidelines

-本文档为 AI 编程助手提供此 TanStack Start 全栈项目的开发规范和指南。
+TanStack Start fullstack web app with ORPC (contract-first RPC).

-## 项目概览
+## Tech Stack

- **框架**: TanStack Start (React SSR 框架，文件路由)
- **运行时**: Bun
- **语言**: TypeScript (strict mode, ESNext)
- **样式**: Tailwind CSS v4
- **数据库**: PostgreSQL + Drizzle ORM
- **状态管理**: TanStack Query
- **路由**: TanStack Router (文件路由)
- **RPC**: ORPC (类型安全 RPC，契约优先)
- **构建工具**: Vite + Turbo
- **代码质量**: Biome (格式化 + Lint)
- **桌面壳** (可选): Tauri v2 (详见 `src-tauri/AGENTS.md`)
+> **⚠️ This project uses Bun — NOT Node.js / npm. All commands use `bun`. Never use `npm`, `npx`, or `node`.**

-## 构建、Lint 和测试命令
+- **Framework**: TanStack Start (React 19 SSR, file-based routing)
+- **Runtime**: Bun — **NOT Node.js**
+- **Package Manager**: Bun — **NOT npm / yarn / pnpm**
+- **Language**: TypeScript (strict mode)
+- **Styling**: Tailwind CSS v4
+- **Database**: PostgreSQL + Drizzle ORM
+- **State**: TanStack Query v5
+- **RPC**: ORPC (contract-first, type-safe)
+- **Build**: Vite + Nitro
+
+## Commands

-### 开发
 ```bash
-bun dev                    # 使用 Turbo 并行启动 Tauri + Vite 开发服务器
-bun dev:vite               # 仅启动 Vite 开发服务器 (localhost:3000)
-bun dev:tauri              # 启动 Tauri 桌面应用
-bun db:studio              # 打开 Drizzle Studio 数据库管理界面
+# Development
+bun dev                    # Vite dev server (localhost:3000)
+bun db:studio              # Drizzle Studio GUI
+
+# Build
+bun build                  # Production build → .output/
+bun compile                # Compile to standalone binary
+
+# Code Quality
+bun fix                    # Biome auto-fix
+bun typecheck              # TypeScript check
+
+# Database
+bun db:generate            # Generate migrations from schema
+bun db:migrate             # Run migrations
+bun 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
 ```

-### 构建
-```bash
-bun build                  # 完整构建 (Vite → 编译 → Tauri 打包)
-bun build:vite             # 仅构建 Vite (输出到 .output/)
-bun build:compile          # 编译为独立可执行文件 (使用 build.ts)
-bun build:tauri            # 构建 Tauri 桌面安装包
+## Directory Structure
+
+```
+src/
+├── client/                # Client-side code
+│   ├── orpc.client.ts     # ORPC isomorphic client
+│   └── query-client.ts    # TanStack Query client
+├── components/            # React components
+├── routes/                # TanStack Router file routes
+│   ├── __root.tsx         # Root layout
+│   ├── index.tsx          # Home page
+│   └── api/
+│       └── rpc.$.ts       # ORPC HTTP endpoint
+├── server/                # Server-side code
+│   ├── api/               # ORPC layer
+│   │   ├── contracts/     # Input/output schemas (Zod)
+│   │   ├── middlewares/   # Middleware (db provider, auth)
+│   │   ├── routers/       # Handler implementations
+│   │   ├── context.ts     # Request context
+│   │   ├── server.ts      # ORPC server instance
+│   │   └── types.ts       # Type exports
+│   └── db/
+│       ├── schema/        # Drizzle table definitions
+│       └── index.ts       # Database instance
+├── env.ts                 # Environment variable validation
+├── router.tsx             # Router configuration
+├── routeTree.gen.ts       # Auto-generated (DO NOT EDIT)
+└── styles.css             # Tailwind entry
 ```

-### 代码质量
-```bash
-bun typecheck              # 运行 TypeScript 编译器检查 (tsc -b)
-bun fix                    # 运行 Biome 自动修复格式和 Lint 问题
-biome check .              # 检查但不自动修复
-biome format --write .     # 仅格式化代码
-```
+## ORPC Pattern

-### 数据库
-```bash
-bun db:generate            # 从 schema 生成迁移文件
-bun db:migrate             # 执行数据库迁移
-bun db:push                # 直接推送 schema 变更 (仅开发环境)
-```
-
-### 测试
-**注意**: 当前未配置测试框架。添加测试时:
- 使用 Vitest 或 Bun 内置测试运行器
- 运行单个测试文件: `bun test path/to/test.ts`
- 运行特定测试: `bun test -t "测试名称模式"`
-
-## 代码风格指南
-
-### 格式化 (Biome)
-
-**缩进**: 2 空格 (不使用 tab)
-**换行符**: LF (Unix 风格)
-**引号**: 单引号 `'string'`
-**分号**: 按需 (ASI - 自动分号插入)
-**箭头函数括号**: 始终使用 `(x) => x`
-
-示例:
+### 1. Define Contract (`src/server/api/contracts/feature.contract.ts`)
 ```typescript
-const myFunc = (value: string) => {
-  return value.toUpperCase()
-}
-```
-
-### 导入组织
-
-Biome 自动组织导入。顺序:
-1. 外部依赖
-2. 内部导入 (使用 `@/*` 别名)
-3. 类型导入 (仅导入类型时使用 `type` 关键字)
-
-示例:
-```typescript
-import { createFileRoute } from '@tanstack/react-router'
 import { oc } from '@orpc/contract'
+import { createSelectSchema } from 'drizzle-zod'
 import { z } from 'zod'
-import { db } from '@/db'
-import { todoTable } from '@/db/schema'
-import type { ReactNode } from 'react'
+import { featureTable } from '@/server/db/schema'
+
+const selectSchema = createSelectSchema(featureTable)
+
+export const list = oc.input(z.void()).output(z.array(selectSchema))
+export const create = oc.input(insertSchema).output(selectSchema)
 ```

-### TypeScript
-
-**严格模式**: 启用了额外的严格检查
- `strict: true`
- `noUncheckedIndexedAccess: true` - 数组/对象索引返回 `T | undefined`
- `noImplicitOverride: true`
- `noFallthroughCasesInSwitch: true`
-
-**模块解析**: `bundler` 模式 + `verbatimModuleSyntax`
- 导入时始终使用 `.ts`/`.tsx` 扩展名
- 使用 `@/*` 路径别名指向 `src/*`
-
-**类型注解**:
- 公共 API 的函数参数和返回类型必须注解
- 优先使用显式类型而非 `any`
- 对象形状用 `type`，可扩展契约用 `interface`
- 不可变 props 使用 `Readonly<T>`
-
-### 命名规范
-
- **文件**: 工具函数用 kebab-case，组件用 PascalCase
-  - `utils.ts`, `todo.tsx`, `NotFound.tsx`
- **路由**: 遵循 TanStack Router 约定
-  - `routes/index.tsx` → `/`
-  - `routes/__root.tsx` → 根布局
- **组件**: PascalCase 箭头函数 (Biome 规则 `useArrowFunction` 强制)
- **函数**: camelCase
- **常量**: 真常量用 UPPER_SNAKE_CASE，配置对象用 camelCase
- **类型/接口**: PascalCase
-
-### React 模式
-
-**组件**: 使用箭头函数
+### 2. Implement Router (`src/server/api/routers/feature.router.ts`)
 ```typescript
-const MyComponent = ({ title }: { title: string }) => {
-  return <div>{title}</div>
-}
-```
+import { ORPCError } from '@orpc/server'
+import { db } from '../middlewares'
+import { os } from '../server'

-**路由**: 使用 `createFileRoute` 定义路由
-```typescript
-export const Route = createFileRoute('/')({
-  component: Home,
+export const list = os.feature.list.use(db).handler(async ({ context }) => {
+  return await context.db.query.featureTable.findMany()
 })
 ```

-**数据获取**: 使用 TanStack Query hooks
- `useSuspenseQuery` - 保证有数据
- `useQuery` - 数据可能为空
+### 3. Register in Index Files
+```typescript
+// src/server/api/contracts/index.ts
+import * as feature from './feature.contract'
+export const contract = { feature }

-**Props**: 禁止直接修改 props (Biome 规则 `noReactPropAssignments`)
+// src/server/api/routers/index.ts
+import * as feature from './feature.router'
+export const router = os.router({ feature })
+```

-### 数据库 Schema (Drizzle)
+### 4. Use in Components
+```typescript
+import { useSuspenseQuery, useMutation } from '@tanstack/react-query'
+import { orpc } from '@/client/orpc.client'

- 在 `src/db/schema/*.ts` 定义 schema
- 从 `src/db/schema/index.ts` 导出
- 使用 `drizzle-orm/pg-core` 的 PostgreSQL 类型
- 主键使用 `uuidv7()` (需要 PostgreSQL 扩展)
- 始终包含 `createdAt` 和 `updatedAt` 时间戳
+const { data } = useSuspenseQuery(orpc.feature.list.queryOptions())
+const mutation = useMutation(orpc.feature.create.mutationOptions())
+```
+
+## Database Schema (Drizzle)

-示例:
 ```typescript
 import { pgTable, text, timestamp, uuid } from 'drizzle-orm/pg-core'
 import { sql } from 'drizzle-orm'
@@ -162,116 +131,75 @@ export const myTable = pgTable('my_table', {
 })
 ```

-### 环境变量
+## Code Style

- 使用 `@t3-oss/env-core` 进行类型安全的环境变量验证
- 在 `src/env.ts` 定义 schema
- 服务端变量: 无前缀
- 客户端变量: 必须有 `VITE_` 前缀
- 使用 Zod schema 验证
+### Formatting (Biome)
+- **Indent**: 2 spaces
+- **Quotes**: Single `'`
+- **Semicolons**: Omit (ASI)
+- **Arrow parens**: Always `(x) => x`

-### 错误处理
+### Imports
+Biome auto-organizes:
+1. External packages
+2. Internal `@/*` aliases
+3. Type imports (`import type { ... }`)

- 异步操作使用 try-catch
- 抛出带有描述性消息的错误
- 用户界面错误优先使用 Result 类型或错误边界
- 适当记录错误 (避免记录敏感数据)
-
-### 样式 (Tailwind CSS)
-
- 使用 Tailwind v4 工具类
- 通过 `@/styles.css?url` 导入样式
- 优先使用组合而非自定义 CSS
- 响应式修饰符: `sm:`, `md:`, `lg:`
- UI 文本适当使用中文
-
-## 目录结构
-
-```
-src/
-├── components/            # 可复用 React 组件
-├── db/
-│   ├── schema/           # Drizzle schema 定义
-│   └── index.ts          # 数据库实例
-├── integrations/         # 第三方集成 (TanStack Query/Router)
-├── lib/                  # 工具函数
-├── orpc/                 # ORPC (RPC 层)
-│   ├── contracts/        # 契约定义 (input/output schemas)
-│   ├── handlers/         # 服务端过程实现
-│   ├── middlewares/      # 中间件 (如 DB provider)
-│   ├── contract.ts       # 契约聚合
-│   ├── router.ts         # 路由组合
-│   ├── server.ts         # 服务端实例
-│   └── client.ts         # 同构客户端
-├── routes/               # TanStack Router 文件路由
-│   ├── __root.tsx        # 根布局
-│   ├── index.tsx         # 首页
-│   └── api/rpc.$.ts      # ORPC HTTP 端点
-├── env.ts                # 环境变量验证
-└── router.tsx            # 路由配置
-```
-
-## 重要提示
-
- **禁止** 编辑 `src/routeTree.gen.ts` - 自动生成
- **禁止** 提交 `.env` 文件 - 使用 `.env.example` 作为模板
- **必须** 在提交前运行 `bun fix`
- **必须** 使用 `@/*` 路径别名而非相对导入
- **必须** 利用 React Compiler (babel-plugin-react-compiler) - 避免手动 memoization
-
-## Git 工作流
-
-1. 按照上述风格指南进行修改
-2. 运行 `bun fix` 自动格式化和 lint
-3. 运行 `bun typecheck` 确保类型安全
-4. 使用 `bun dev` 本地测试变更
-5. 使用清晰的描述性消息提交
-
-## 常见模式
-
-### 创建 ORPC 过程
-
-**步骤 1: 定义契约** (`src/orpc/contracts/my-feature.ts`)
 ```typescript
-import { oc } from '@orpc/contract'
+import { createFileRoute } from '@tanstack/react-router'
+import { z } from 'zod'
+import { db } from '@/server/db'
+import type { ReactNode } from 'react'
+```
+
+### TypeScript
+- `strict: true`
+- `noUncheckedIndexedAccess: true` - array access returns `T | undefined`
+- Use `@/*` path aliases (maps to `src/*`)
+
+### Naming
+| Type | Convention | Example |
+|------|------------|---------|
+| Files (utils) | kebab-case | `auth-utils.ts` |
+| Files (components) | PascalCase | `UserProfile.tsx` |
+| Components | PascalCase arrow | `const Button = () => {}` |
+| Functions | camelCase | `getUserById` |
+| Types | PascalCase | `UserProfile` |
+
+### React
+- Use arrow functions for components (Biome enforced)
+- Use `useSuspenseQuery` for guaranteed data
+- Let React Compiler handle memoization (no manual `useMemo`/`useCallback`)
+
+## Environment Variables
+
+```typescript
+// src/env.ts - using @t3-oss/env-core
+import { createEnv } from '@t3-oss/env-core'
 import { z } from 'zod'

-export const myContract = {
-  get: oc.input(z.object({ id: z.uuid() })).output(mySchema),
-  create: oc.input(createSchema).output(mySchema),
-}
+export const env = createEnv({
+  server: {
+    DATABASE_URL: z.string().url(),
+  },
+  clientPrefix: 'VITE_',
+  client: {
+    VITE_API_URL: z.string().optional(),
+  },
+})
 ```

-**步骤 2: 实现处理器** (`src/orpc/handlers/my-feature.ts`)
-```typescript
-import { os } from '@/orpc/server'
-import { dbProvider } from '@/orpc/middlewares'
+## Critical Rules

-export const get = os.myFeature.get
-  .use(dbProvider)
-  .handler(async ({ context, input }) => {
-    return await context.db.query.myTable.findFirst(...)
-  })
-```
+**DO:**
+- Run `bun fix` before committing
+- Use `@/*` path aliases
+- Include `createdAt`/`updatedAt` on all tables
+- Use `ORPCError` with proper codes

-**步骤 3: 注册到契约和路由**
-```typescript
-// src/orpc/contract.ts
-export const contract = { myFeature: myContract }
-
-// src/orpc/router.ts
-import * as myFeature from './handlers/my-feature'
-export const router = os.router({ myFeature })
-```
-
-**步骤 4: 在组件中使用**
-```typescript
-import { orpc } from '@/orpc'
-const query = useSuspenseQuery(orpc.myFeature.get.queryOptions({ id }))
-const mutation = useMutation(orpc.myFeature.create.mutationOptions())
-```
-
---
-
-**最后更新**: 2026-01-18
-**项目版本**: 基于 package.json 依赖版本
+**DON'T:**
+- Use `npm`, `npx`, `node`, `yarn`, `pnpm` — always use `bun` / `bunx`
+- Edit `src/routeTree.gen.ts` (auto-generated)
+- Use `as any`, `@ts-ignore`, `@ts-expect-error`
+- Commit `.env` files
+- Use empty catch blocks
--- a/apps/server/build.ts
+++ b/apps/server/build.ts
@@ -1,289 +1,111 @@
-import { Schema } from '@effect/schema'
-import { $ } from 'bun'
-import { Console, Context, Data, Effect, Layer } from 'effect'
+import { rm } from 'node:fs/promises'
+import path from 'node:path'
+import process from 'node:process'

-// ============================================================================
-// Domain Models & Schema
-// ============================================================================
-
-const BunTargetSchema = Schema.Literal(
+const ALL_TARGETS = [
  'bun-windows-x64',
  'bun-darwin-arm64',
  'bun-darwin-x64',
  'bun-linux-x64',
  'bun-linux-arm64',
-)
+] as const

-/**
- * 将 bun target 转换为文件后缀 (去掉 'bun-' 前缀)
- */
-const getTargetSuffix = (target: BunTarget): string => {
-  return target.replace('bun-', '')
-}
+type BunTarget = (typeof ALL_TARGETS)[number]

-type BunTarget = Schema.Schema.Type<typeof BunTargetSchema>
+const ENTRYPOINT = '.output/server/index.mjs'
+const OUTDIR = 'out'
+const OUTFILE_BASE = 'server'

-const BuildConfigSchema = Schema.Struct({
-  entrypoint: Schema.String.pipe(Schema.nonEmptyString()),
-  outputDir: Schema.String.pipe(Schema.nonEmptyString()),
-  outfile: Schema.String.pipe(Schema.nonEmptyString()),
-  targets: Schema.Array(BunTargetSchema).pipe(Schema.minItems(1)),
-})
+const DEFAULT_TARGETS: BunTarget[] = [
+  'bun-windows-x64',
+  'bun-darwin-arm64',
+  'bun-linux-x64',
+]

-type BuildConfig = Schema.Schema.Type<typeof BuildConfigSchema>
+const suffixFor = (target: BunTarget) => target.replace('bun-', '')

-const BuildResultSchema = Schema.Struct({
-  target: BunTargetSchema,
-  outputs: Schema.Array(Schema.String),
-})
+const isTarget = (value: string): value is BunTarget =>
+  (ALL_TARGETS as readonly string[]).includes(value)

-type BuildResult = Schema.Schema.Type<typeof BuildResultSchema>
+const parseTargets = (): BunTarget[] => {
+  const args = process.argv.slice(2)
+  const targets: string[] = []

-// ============================================================================
-// Error Models (使用 Data.TaggedError)
-// ============================================================================
-
-class CleanError extends Data.TaggedError('CleanError')<{
-  readonly dir: string
-  readonly cause: unknown
-}> {}
-
-class BuildError extends Data.TaggedError('BuildError')<{
-  readonly target: BunTarget
-  readonly cause: unknown
-}> {}
-
-class ConfigError extends Data.TaggedError('ConfigError')<{
-  readonly message: string
-  readonly cause: unknown
-}> {}
-
-// ============================================================================
-// Services
-// ============================================================================
-
-/**
- * 配置服务
- */
-class BuildConfigService extends Context.Tag('BuildConfigService')<
-  BuildConfigService,
-  BuildConfig
->() {
-  /**
-   * 从原始数据创建并验证配置
-   */
-  static fromRaw = (raw: unknown) =>
-    Effect.gen(function* () {
-      const decoded = yield* Schema.decodeUnknown(BuildConfigSchema)(raw)
-      return decoded
-    }).pipe(
-      Effect.catchAll((error) =>
-        Effect.fail(
-          new ConfigError({
-            message: '配置验证失败',
-            cause: error,
-          }),
-        ),
-      ),
-    )
-
-  /**
-   * 默认配置 Layer
-   */
-  static readonly Live = Layer.effect(
-    BuildConfigService,
-    BuildConfigService.fromRaw({
-      entrypoint: '.output/server/index.mjs',
-      outputDir: 'out',
-      outfile: 'server',
-      targets: ['bun-windows-x64', 'bun-darwin-arm64', 'bun-linux-x64'],
-    } satisfies BuildConfig),
-  )
-}
-
-/**
- * 文件系统服务
- */
-class FileSystemService extends Context.Tag('FileSystemService')<
-  FileSystemService,
-  {
-    readonly cleanDir: (dir: string) => Effect.Effect<void, CleanError>
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+    const next = args[i + 1]
+    if (arg === '--target' && next) {
+      targets.push(next)
+      i++
+    } else if (arg === '--targets' && next) {
+      targets.push(...next.split(','))
+      i++
    }
->() {
-  static readonly Live = Layer.succeed(FileSystemService, {
-    cleanDir: (dir: string) =>
-      Effect.tryPromise({
-        try: async () => {
-          await $`rm -rf ${dir}`
-        },
-        catch: (cause: unknown) =>
-          new CleanError({
-            dir,
-            cause,
-          }),
-      }),
-  })
+  }
+
+  if (targets.length === 0) return DEFAULT_TARGETS
+
+  const invalid = targets.filter((t) => !isTarget(t))
+  if (invalid.length) {
+    throw new Error(
+      `Unknown target(s): ${invalid.join(', ')}\nAllowed: ${ALL_TARGETS.join(', ')}`,
+    )
+  }
+  return targets as BunTarget[]
 }

-/**
- * 构建服务
- */
-class BuildService extends Context.Tag('BuildService')<
-  BuildService,
-  {
-    readonly buildForTarget: (
-      config: BuildConfig,
-      target: BunTarget,
-    ) => Effect.Effect<BuildResult, BuildError>
-    readonly buildAll: (
-      config: BuildConfig,
-    ) => Effect.Effect<ReadonlyArray<BuildResult>, BuildError>
-  }
->() {
-  static readonly Live = Layer.succeed(BuildService, {
-    buildForTarget: (config: BuildConfig, target: BunTarget) =>
-      Effect.gen(function* () {
-        yield* Console.log(`🔨 开始构建: ${target}`)
+const buildOne = async (target: BunTarget) => {
+  const suffix = suffixFor(target)
+  const outfile = `${OUTFILE_BASE}-${suffix}`

-        const output = yield* Effect.tryPromise({
-          try: () =>
-            Bun.build({
-              entrypoints: [config.entrypoint],
+  const result = await Bun.build({
+    entrypoints: [ENTRYPOINT],
+    outdir: OUTDIR,
    compile: {
-                outfile: `${config.outfile}-${getTargetSuffix(target)}`,
-                target: target,
-              },
-              outdir: config.outputDir,
-            }),
-          catch: (cause: unknown) =>
-            new BuildError({
+      outfile,
      target,
-              cause,
-            }),
+    },
  })

-        const paths = output.outputs.map((item: { path: string }) => item.path)
+  if (!result.success) {
+    throw new Error(
+      `Build failed for ${target}:\n${result.logs.map(String).join('\n')}`,
+    )
+  }

  return {
    target,
-          outputs: paths,
-        } satisfies BuildResult
-      }),
-
-    buildAll: (config: BuildConfig) =>
-      Effect.gen(function* () {
-        const effects = config.targets.map((target) =>
-          Effect.gen(function* () {
-            yield* Console.log(`🔨 开始构建: ${target}`)
-
-            const output = yield* Effect.tryPromise({
-              try: () =>
-                Bun.build({
-                  entrypoints: [config.entrypoint],
-                  compile: {
-                    outfile: `${config.outfile}-${getTargetSuffix(target)}`,
-                    target: target,
-                  },
-                  outdir: config.outputDir,
-                }),
-              catch: (cause: unknown) =>
-                new BuildError({
-                  target,
-                  cause,
-                }),
-            })
-
-            const paths = output.outputs.map(
-              (item: { path: string }) => item.path,
-            )
-
-            return {
-              target,
-              outputs: paths,
-            } satisfies BuildResult
-          }),
-        )
-        return yield* Effect.all(effects, { concurrency: 'unbounded' })
-      }),
-  })
+    outputs: result.outputs.map((o) => path.relative('.', o.path)),
+  }
 }

-/**
- * 报告服务
- */
-class ReporterService extends Context.Tag('ReporterService')<
-  ReporterService,
-  {
-    readonly printSummary: (
-      results: ReadonlyArray<BuildResult>,
-    ) => Effect.Effect<void>
+const main = async () => {
+  const targets = parseTargets()
+
+  await rm(OUTDIR, { recursive: true, force: true })
+  console.log(`✓ 已清理输出目录: ${OUTDIR}`)
+
+  // Bun cross-compile 不支持真正并行，逐目标串行构建
+  const results: Awaited<ReturnType<typeof buildOne>>[] = []
+  for (const target of targets) {
+    const start = Date.now()
+    process.stdout.write(`🔨 构建 ${target}... `)
+    const result = await buildOne(target)
+    results.push(result)
+    console.log(`完成 (${Date.now() - start}ms)`)
  }
->() {
-  static readonly Live = Layer.succeed(ReporterService, {
-    printSummary: (results: ReadonlyArray<BuildResult>) =>
-      Effect.gen(function* () {
-        yield* Console.log('\n📦 构建完成:')
-        for (const result of results) {
-          yield* Console.log(`  ${result.target}:`)
-          for (const path of result.outputs) {
-            yield* Console.log(`    - ${path}`)
+
+  console.log('\n📦 构建完成:')
+  for (const r of results) {
+    console.log(`  ${r.target}:`)
+    for (const p of r.outputs) {
+      console.log(`    - ${p}`)
    }
  }
-      }),
-  })
 }

-// ============================================================================
-// Main Program
-// ============================================================================
-
-const program = Effect.gen(function* () {
-  const config = yield* BuildConfigService
-  const fs = yield* FileSystemService
-  const builder = yield* BuildService
-  const reporter = yield* ReporterService
-
-  // 1. 清理输出目录
-  yield* fs.cleanDir(config.outputDir)
-  yield* Console.log(`✓ 已清理输出目录: ${config.outputDir}`)
-
-  // 2. 并行构建所有目标
-  const results = yield* builder.buildAll(config)
-
-  // 3. 输出构建摘要
-  yield* reporter.printSummary(results)
-
-  return results
-})
-
-// ============================================================================
-// Layer Composition
-// ============================================================================
-
-const MainLayer = Layer.mergeAll(
-  BuildConfigService.Live,
-  FileSystemService.Live,
-  BuildService.Live,
-  ReporterService.Live,
-)
-
-// ============================================================================
-// Runner
-// ============================================================================
-
-const runnable = program.pipe(
-  Effect.provide(MainLayer),
-  Effect.catchTags({
-    CleanError: (error) =>
-      Console.error(`❌ 清理目录失败: ${error.dir}`, error.cause),
-    BuildError: (error) =>
-      Console.error(`❌ 构建失败 [${error.target}]:`, error.cause),
-    ConfigError: (error) =>
-      Console.error(`❌ 配置错误: ${error.message}`, error.cause),
-  }),
-  Effect.tapErrorCause((cause) => Console.error('❌ 未预期的错误:', cause)),
-)
-
-Effect.runPromise(runnable).catch(() => {
+main().catch((err) => {
+  console.error('\n❌ 构建失败:')
+  console.error(err instanceof Error ? err.message : err)
  process.exit(1)
 })
--- a/apps/server/package.json
+++ b/apps/server/package.json
@@ -27,7 +27,6 @@
    "@tanstack/react-router": "catalog:",
    "@tanstack/react-router-ssr-query": "catalog:",
    "@tanstack/react-start": "catalog:",
-    "@tauri-apps/api": "catalog:",
    "drizzle-orm": "catalog:",
    "drizzle-zod": "catalog:",
    "postgres": "catalog:",
@@ -37,8 +36,6 @@
    "zod": "catalog:"
  },
  "devDependencies": {
-    "@effect/platform": "catalog:",
-    "@effect/schema": "catalog:",
    "@furtherverse/tsconfig": "workspace:*",
    "@tailwindcss/vite": "catalog:",
    "@tanstack/devtools-vite": "catalog:",
@@ -49,10 +46,8 @@
    "@vitejs/plugin-react": "catalog:",
    "babel-plugin-react-compiler": "catalog:",
    "drizzle-kit": "catalog:",
-    "effect": "catalog:",
    "nitro": "catalog:",
    "tailwindcss": "catalog:",
-    "typescript": "catalog:",
    "vite": "catalog:",
    "vite-tsconfig-paths": "catalog:"
  }
--- a/apps/server/src/routes/index.tsx
+++ b/apps/server/src/routes/index.tsx
@@ -1,9 +1,7 @@
 import { useMutation, useSuspenseQuery } from '@tanstack/react-query'
 import { createFileRoute } from '@tanstack/react-router'
-import { isTauri } from '@tauri-apps/api/core'
-import { getCurrentWindow } from '@tauri-apps/api/window'
 import type { ChangeEventHandler, FormEventHandler } from 'react'
-import { useEffect, useState } from 'react'
+import { useState } from 'react'
 import { orpc } from '@/client/query-client'

 export const Route = createFileRoute('/')({
@@ -21,11 +19,6 @@ function Todos() {
  const updateMutation = useMutation(orpc.todo.update.mutationOptions())
  const deleteMutation = useMutation(orpc.todo.remove.mutationOptions())

-  useEffect(() => {
-    if (!isTauri()) return
-    getCurrentWindow().setTitle('待办事项')
-  }, [])
-
  const handleCreateTodo: FormEventHandler<HTMLFormElement> = (e) => {
    e.preventDefault()
    if (newTodoTitle.trim()) {
--- a/apps/server/turbo.json
+++ b/apps/server/turbo.json
@@ -2,8 +2,11 @@
  "$schema": "../../node_modules/turbo/schema.json",
  "extends": ["//"],
  "tasks": {
+    "build": {
+      "env": ["NODE_ENV", "VITE_*"],
+      "outputs": [".output/**"]
+    },
    "compile": {
-      "dependsOn": ["build"],
      "outputs": ["out/**"]
    }
  }
--- a/bun.lock
+++ b/bun.lock
--- a/mise.toml
+++ b/mise.toml
@@ -1,4 +1,3 @@
 [tools]
-node = "latest"
 bun = "1"
-rust = 'latest'
+node = "24"
--- a/package.json
+++ b/package.json
@@ -10,19 +10,17 @@
  "scripts": {
    "build": "turbo run build",
    "compile": "turbo run compile",
-    "deploy": "turbo run deploy",
    "dev": "turbo run dev",
    "fix": "turbo run fix",
    "typecheck": "turbo run typecheck"
  },
  "devDependencies": {
-    "@biomejs/biome": "^2.3.11",
-    "turbo": "^2.7.5"
+    "@biomejs/biome": "^2.3.14",
+    "turbo": "^2.8.3",
+    "typescript": "^5.9.3"
  },
  "catalog": {
    "@biomejs/biome": "^2.3.11",
-    "@effect/platform": "^0.94.2",
-    "@effect/schema": "^0.75.5",
    "@orpc/client": "^1.13.4",
    "@orpc/contract": "^1.13.4",
    "@orpc/openapi": "^1.13.4",
@@ -31,35 +29,37 @@
    "@orpc/zod": "^1.13.4",
    "@t3-oss/env-core": "^0.13.10",
    "@tailwindcss/vite": "^4.1.18",
-    "@tanstack/devtools-vite": "^0.4.1",
-    "@tanstack/react-devtools": "^0.9.2",
-    "@tanstack/react-query": "^5.90.19",
-    "@tanstack/react-query-devtools": "^5.91.2",
-    "@tanstack/react-router": "^1.154.12",
-    "@tanstack/react-router-devtools": "^1.154.12",
-    "@tanstack/react-router-ssr-query": "^1.154.12",
-    "@tanstack/react-start": "^1.154.12",
-    "@tauri-apps/api": "^2.9.1",
-    "@tauri-apps/cli": "^2.9.6",
-    "@types/bun": "^1.3.6",
-    "@vitejs/plugin-react": "^5.1.2",
+    "@tanstack/devtools-vite": "^0.5.0",
+    "@tanstack/react-devtools": "^0.9.4",
+    "@tanstack/react-query": "^5.90.20",
+    "@tanstack/react-query-devtools": "^5.91.3",
+    "@tanstack/react-router": "^1.158.4",
+    "@tanstack/react-router-devtools": "^1.158.4",
+    "@tanstack/react-router-ssr-query": "^1.158.4",
+    "@tanstack/react-start": "^1.159.0",
+    "@types/bun": "^1.3.8",
+    "@types/node": "^24.3.0",
+    "@vitejs/plugin-react": "^5.1.3",
    "babel-plugin-react-compiler": "^1.0.0",
    "drizzle-kit": "^0.31.8",
    "drizzle-orm": "^0.45.1",
    "drizzle-zod": "^0.8.3",
-    "effect": "^3.19.15",
-    "nitro": "npm:nitro-nightly@3.0.1-20260122-201913-dfdff9e9",
+    "electrobun": "^1.12.0-beta.1",
+    "nitro": "npm:nitro-nightly@3.0.1-20260206-171553-bc737c0c",
    "ohash": "^2.0.11",
    "postgres": "^3.4.8",
-    "react": "^19.2.3",
-    "react-dom": "^19.2.3",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "systeminformation": "^5.30.7",
    "tailwindcss": "^4.1.18",
    "turbo": "^2.7.5",
    "typescript": "^5.9.3",
    "uuid": "^13.0.0",
-    "systeminformation": "^5.30.5",
-    "vite": "^8.0.0-beta.9",
-    "vite-tsconfig-paths": "^6.0.4",
+    "vite": "^8.0.0-beta.13",
+    "vite-tsconfig-paths": "^6.0.5",
    "zod": "^4.3.6"
+  },
+  "overrides": {
+    "@types/node": "catalog:"
  }
 }
--- a/packages/utils/package.json
+++ b/packages/utils/package.json
@@ -15,7 +15,6 @@
    "systeminformation": "catalog:"
  },
  "devDependencies": {
-    "@furtherverse/tsconfig": "workspace:*",
-    "typescript": "catalog:"
+    "@furtherverse/tsconfig": "workspace:*"
  }
 }
--- a/turbo.json
+++ b/turbo.json
@@ -1,30 +1,28 @@
 {
  "$schema": "./node_modules/turbo/schema.json",
  "dangerouslyDisablePackageManagerCheck": true,
-  "globalDependencies": [
-    "package.json",
-    "bun.lock",
-    "turbo.json",
-    "biome.json"
-  ],
+  "globalDependencies": ["bun.lock"],
  "tasks": {
    "build": {
-      "outputs": ["dist/**", ".output/**"]
+      "dependsOn": ["^build"]
    },
    "compile": {
-      "dependsOn": ["build"],
-      "outputs": ["out/**"]
+      "dependsOn": ["build"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "fix": {
-      "outputs": []
+      "cache": false
    },
    "typecheck": {
-      "dependsOn": ["^typecheck"],
-      "inputs": ["tsconfig.json", "tsconfig.*.json", "**/*.{ts,tsx}"],
+      "inputs": [
+        "package.json",
+        "tsconfig.json",
+        "tsconfig.*.json",
+        "**/*.{ts,tsx,d.ts}"
+      ],
      "outputs": []
    }
  },
Author	SHA1	Message	Date
imbytecat	70b5d27493	chore(desktop): 添加 win-x64 构建目标	2026-02-07 21:04:39 +08:00
imbytecat	5d5d3a51f6	chore(desktop): 禁用 mac 和 win 平台的 CEF 捆绑	2026-02-07 20:57:58 +08:00
imbytecat	3306e18395	refactor(desktop): 使用预分配端口替代 stdout 解析获取服务器端口	2026-02-07 19:32:56 +08:00
imbytecat	14bcdb33af	chore(deps): 升级 TanStack 路由和 Start 依赖版本	2026-02-07 19:11:28 +08:00
imbytecat	cc81d95178	chore(desktop): 升级 electrobun 至 1.12.0-beta.1	2026-02-07 19:10:33 +08:00
imbytecat	55d45e6a49	docs(desktop): 更新 AGENTS.md 文档与开发计划以反映最新实现	2026-02-07 18:49:50 +08:00
imbytecat	b7a6a793a3	feat(desktop): 实现生产模式下的内嵌服务器子进程支持	2026-02-07 18:49:41 +08:00
imbytecat	6b12745e50	chore(desktop): 更新应用名称、标识符和版本号	2026-02-07 17:46:00 +08:00
imbytecat	989d8973f5	chore(desktop): 简化构建和开发脚本	2026-02-07 17:16:32 +08:00
imbytecat	41e79449ce	docs: 更新 AGENTS.md 适配 Electrobun 替代 Tauri	2026-02-07 17:00:52 +08:00
imbytecat	4bbb0c4a16	refactor(server): simplify build script, remove Effect dependency	2026-02-07 16:44:56 +08:00
imbytecat	2b3026cf69	chore(turbo): simplify and optimize monorepo configuration	2026-02-07 16:35:30 +08:00
imbytecat	adb14cff77	chore: 重构 Turbo 构建配置并强化 Bun 专用说明将应用特定的构建输出配置下沉至各自 turbo.json，根级 build 任务添加拓扑依赖；AGENTS.md 统一添加 Bun 专用运行时警告；桌面端启用 Linux CEF 渲染器。	2026-02-07 16:14:55 +08:00
imbytecat	44ca7a0f5e	chore: 扩展 Turbo build 任务的输出目录配置	2026-02-07 07:06:55 +08:00
imbytecat	59b4edc2d2	chore(desktop): 降级 electrobun 至 0.8.0 稳定版	2026-02-07 06:59:19 +08:00
imbytecat	9d0e9a6aac	chore(desktop): 添加 .gitignore 和多平台构建脚本	2026-02-07 06:29:08 +08:00
imbytecat	f758fd5947	chore: 更新 bun.lock 锁文件	2026-02-07 06:15:52 +08:00
imbytecat	26f9421130	chore: 统一 Node/TypeScript 配置并修复桌面端类型环境	2026-02-07 05:53:38 +08:00
imbytecat	29969550ed	refactor(desktop): 从 Tauri 迁移到 Electrobun - 移除 Tauri v2 代码 (src-tauri/, copy.ts) - 添加 Electrobun 配置和入口 (electrobun.config.ts, src/bun/index.ts) - 更新 package.json 使用 catalog 管理 electrobun 依赖 - 移除 server 中的 @tauri-apps/api 依赖 - 更新 AGENTS.md 文档	2026-02-07 05:04:53 +08:00
imbytecat	9aa3b46ee5	chore(desktop): 更新 Cargo 依赖	2026-02-07 03:45:08 +08:00
imbytecat	f3ea0f0789	chore: 更新依赖版本	2026-02-07 03:32:42 +08:00
imbytecat	bde325d9ae	chore: 更新 biome 和 turbo 依赖版本	2026-02-07 03:31:01 +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