docs(readme): 强调 PostgreSQL 18+ 要求并提供 escape hatch

代码 schema 用了 PG 原生 uuidv7() 函数，PG <18 会炸。在技术栈行里把
PostgreSQL 改成 PostgreSQL 18+，快速开始顶部加 callout 说明改回
Bun.randomUUIDv7() 的方式以兼容老版本。

.dockerignore

@@ -0,0 +1,13 @@
+node_modules/
+.output/
+.tanstack/
+out/
+.git/
+.env
+.env.*
+
+*.md
+*.tsbuildinfo
+*.bun-build
+
+.vscode/

.env.example

@@ -0,0 +1,6 @@
+DATABASE_URL=postgres://postgres:postgres@localhost:5432/postgres
+
+# Optional logging knobs (defaults are usually fine):
+# LOG_LEVEL=info       # trace|debug|info|warning|error|fatal
+# LOG_FORMAT=pretty    # pretty|json — defaults to TTY ? pretty : json
+# LOG_DB=false         # true to log every Drizzle SQL query

.gitignore

@@ -1,157 +1,23 @@
-### Custom ###
+# Dependencies
-
-# TanStack
-.tanstack/
-
-# Nitro
-.output/
-
-# Bun build
-*.bun-build
-
-# Turborepo
-.turbo/
-
-### Node ###
-
-# Logs
-logs
-*.log
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-lerna-debug.log*
-
-# Diagnostic reports (https://nodejs.org/api/report.html)
-report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
-
-# Runtime data
-pids
-*.pid
-*.seed
-*.pid.lock
-
-# Directory for instrumented libs generated by jscoverage/JSCover
-lib-cov
-
-# Coverage directory used by tools like istanbul
-coverage
-*.lcov
-
-# nyc test coverage
-.nyc_output
-
-# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
-.grunt
-
-# Bower dependency directory (https://bower.io/)
-bower_components
-
-# node-waf configuration
-.lock-wscript
-
-# Compiled binary addons (https://nodejs.org/api/addons.html)
-build/Release
-
-# Dependency directories
 node_modules/
-jspm_packages/
 
-# Snowpack dependency directory (https://snowpack.dev/)
+# Build output
-web_modules/
+.output/
-
+.tanstack/
-# TypeScript cache
+.vite/
+out/
+*.bun-build
 *.tsbuildinfo
+vite.config.js.timestamp-*
+vite.config.ts.timestamp-*
 
-# Optional npm cache directory
+# Env
-.npm
-
-# Optional eslint cache
-.eslintcache
-
-# Optional stylelint cache
-.stylelintcache
-
-# Optional REPL history
-.node_repl_history
-
-# Output of 'npm pack'
-*.tgz
-
-# Yarn Integrity file
-.yarn-integrity
-
-# dotenv environment variable files
 .env
 .env.*
 !.env.example
 
-# parcel-bundler cache (https://parceljs.org/)
+# Logs
-.cache
+*.log
-.parcel-cache
 
-# Next.js build output
+# OS
-.next
+.DS_Store
-out
-
-# Nuxt.js build / generate output
-.nuxt
-dist
-.output
-
-# Gatsby files
-.cache/
-# Comment in the public line in if your project uses Gatsby and not Next.js
-# https://nextjs.org/blog/next-9-1#public-directory-support
-# public
-
-# vuepress build output
-.vuepress/dist
-
-# vuepress v2.x temp and cache directory
-.temp
-.cache
-
-# Sveltekit cache directory
-.svelte-kit/
-
-# vitepress build output
-**/.vitepress/dist
-
-# vitepress cache directory
-**/.vitepress/cache
-
-# Docusaurus cache and generated files
-.docusaurus
-
-# Serverless directories
-.serverless/
-
-# FuseBox cache
-.fusebox/
-
-# DynamoDB Local files
-.dynamodb/
-
-# Firebase cache directory
-.firebase/
-
-# TernJS port file
-.tern-port
-
-# Stores VSCode versions used for testing VSCode extensions
-.vscode-test
-
-# yarn v3
-.pnp.*
-.yarn/*
-!.yarn/patches
-!.yarn/plugins
-!.yarn/releases
-!.yarn/sdks
-!.yarn/versions
-
-# Vite files
-vite.config.js.timestamp-*
-vite.config.ts.timestamp-*
-.vite/

.vscode/extensions.json

@@ -1,9 +1,11 @@
 {
   "recommendations": [
     "biomejs.biome",
+    "codezombiech.gitignore",
     "hverlin.mise-vscode",
     "oven.bun-vscode",
     "redhat.vscode-yaml",
-    "tamasfe.even-better-toml"
+    "tamasfe.even-better-toml",
+    "unional.vscode-sort-package-json"
   ]
 }

.vscode/settings.json

@@ -43,6 +43,8 @@
   "files.watcherExclude": {
     "**/routeTree.gen.ts": true
   },
+  "js/ts.tsdk.path": "node_modules/typescript/lib",
+  "js/ts.tsdk.promptToUseWorkspaceVersion": true,
   "search.exclude": {
     "**/routeTree.gen.ts": true
   }

AGENTS.md

@@ -1,219 +1,232 @@
-# AGENTS.md - AI Coding Agent Guidelines
+# AGENTS.md
 
-Guidelines for AI agents working in this Bun monorepo.
+Compact, repo-specific notes for AI agents. Generic language/framework knowledge is omitted — only things that will bite you if you don't know. Pair this with `README.md` (user-facing quick-start + add-a-feature checklist + deploy flow).
 
-## Project Overview
+## Stack & runtime
 
-> **This project uses [Bun](https://bun.sh) exclusively as both the JavaScript runtime and package manager. Do NOT use Node.js / npm / yarn / pnpm. All commands start with `bun` — use `bun install` for dependencies and `bun run <script>` for scripts. Always prefer `bun run <script>` over `bun <script>` to avoid conflicts with Bun built-in subcommands (e.g. `bun build` invokes Bun's bundler, NOT your package.json script). Never use `npm`, `npx`, or `node`.**
+- **Bun-only** (`mise.toml` pins `bun = 1.3.13`). Never invoke `npm`/`npx`/`node`/`yarn`/`pnpm`. Use `bun run <script>` (bare `bun <script>` can collide with Bun built-in subcommands).
+- **Prefer Bun-native APIs over external packages and `node:*` polyfills.** UUIDv7 in app code → `Bun.randomUUIDv7()` (not the `uuid` package); DB primary keys are a separate matter — those go through PG18's `uuidv7()`, see "Drizzle" section. SHA-256 → `Bun.CryptoHasher.hash('sha256', s, 'hex')` (not `node:crypto.createHash`); short sleeps → `Bun.sleep(ms)` (not raw `setTimeout` with promise wrapping); file I/O in build scripts → `Bun.file` / `Bun.write` are fine. The runtime is Bun, the deployment target is Bun, the test runner is Bun — there is no "portability" concern that would justify dragging in npm packages or Node compat shims for things Bun ships natively.
+- TanStack Start (React 19 SSR, file-routed) + Vite 8 + Nitro (nightly, preset `bun`). Dev server defaults to Vite's port (3000); not pinned, override via `vite dev --port <n>` if you need to.
+- **PostgreSQL 18+ only** (`compose.yaml` pins `postgres:18-alpine`). The starter relies on PG18's built-in `uuidv7()` function for primary-key generation — see "Drizzle" section. Do not soften this to support older PG; if you need PG <18 compatibility, fork and reintroduce app-side UUIDv7 (e.g. `Bun.randomUUIDv7()` or the `uuid` package) yourself.
+- **Drizzle ORM `0.45.2` (0.x, NOT 1.0 beta)** — see "Drizzle" section, this matters a lot.
+- ORPC (contract-first), TanStack Query v5, Tailwind v4.
+- **Logging via [LogTape](https://logtape.org/)** (zero-dep, runtime-agnostic) — see "Logging" section. `console.*` is forbidden in business code.
 
-- **Monorepo**: Bun workspaces + Turborepo orchestration
+## Scripts
-- **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` - Electron desktop shell, sidecar server pattern (see `apps/desktop/AGENTS.md`)
-- **Packages**: `packages/tsconfig` (shared TS configs)
 
-## Build / Lint / Test Commands
-
-### Root Commands (via Turbo)
 ```bash
-bun run dev              # Start all apps in dev mode
+bun run dev          # bunx --bun vite dev  (localhost:3000)
-bun run build            # Build all apps
+bun run build        # bunx --bun vite build → .output/
-bun run compile          # Compile server to standalone binary (current platform)
+bun run compile      # bun scripts/compile.ts → out/server-<target> (standalone CLI binary)
-bun run compile:darwin   # Compile server for macOS (arm64 + x64)
+bun run cli <cmd>    # bun src/bin.ts <cmd>  — run a CLI subcommand in source (dev)
-bun run compile:linux    # Compile server for Linux (x64 + arm64)
+bun run typecheck    # tsc --noEmit
-bun run compile:windows  # Compile server for Windows x64
+bun run test         # bun test  — runs all *.test.ts files (colocated with source)
-bun run dist             # Package desktop distributable (current platform)
+bun run fix          # biome check --write  (lint + format + organize imports)
-bun run dist:linux       # Package desktop for Linux (x64 + arm64)
+bun run db:push      # dev only — push schema to DB, no migration file
-bun run dist:mac         # Package desktop for macOS (arm64 + x64)
+bun run db:generate  # drizzle-kit generate && scripts/embed-migrations.ts (regenerates migrations.gen.ts)
-bun run dist:win         # Package desktop for Windows x64
+bun run db:embed     # scripts/embed-migrations.ts only — regenerate migrations.gen.ts from ./drizzle/
-bun run fix              # Lint + format (Biome auto-fix)
+bun run db:migrate   # apply migrations via drizzle-kit (local dev convenience; prod uses ./server migrate)
-bun run typecheck        # TypeScript check across monorepo
+bun run db:studio    # Drizzle Studio
 ```
 
-### Server App (`apps/server`)
+Cross-compile targets live under `compile:{linux,darwin,windows}[:arch]`. `scripts/compile.ts` accepts `--target bun-<os>-<arch>`; default derives from host.
-```bash
-bun run dev                   # Vite dev server (localhost:3000)
-bun run build                 # Production build -> .output/
-bun run compile               # Compile to standalone binary (current platform)
-bun run compile:darwin        # Compile for macOS (arm64 + x64)
-bun run compile:darwin:arm64  # Compile for macOS arm64
-bun run compile:darwin:x64    # Compile for macOS x64
-bun run compile:linux         # Compile for Linux (x64 + arm64)
-bun run compile:linux:arm64   # Compile for Linux arm64
-bun run compile:linux:x64     # Compile for Linux x64
-bun run compile:windows       # Compile for Windows (default: x64)
-bun run compile:windows:x64   # Compile for Windows x64
-bun run fix                   # Biome auto-fix
-bun run typecheck             # TypeScript check
 
-# Database (Drizzle)
+Before committing: `bun run fix && bun run typecheck && bun run test`. No CI, no pre-commit hooks, no lint-staged — so these are on you.
-bun run db:generate           # Generate migrations from schema
-bun run db:migrate            # Run migrations
-bun run db:push               # Push schema (dev only)
-bun run db:studio             # Open Drizzle Studio
-```
 
-### Desktop App (`apps/desktop`)
+## Drizzle (v0.x — critical)
-```bash
-bun run dev                   # electron-vite dev mode (requires server dev running)
-bun run build                 # electron-vite build (main + preload)
-bun run dist                  # Build + package for current platform
-bun run dist:linux            # Build + package for Linux (x64 + arm64)
-bun run dist:linux:x64        # Build + package for Linux x64
-bun run dist:linux:arm64      # Build + package for Linux arm64
-bun run dist:mac              # Build + package for macOS (arm64 + x64)
-bun run dist:mac:arm64        # Build + package for macOS arm64
-bun run dist:mac:x64          # Build + package for macOS x64
-bun run dist:win              # Build + package for Windows x64
-bun run fix                   # Biome auto-fix
-bun run typecheck             # TypeScript check
-```
 
-### Testing
+**Why it matters:** the project was on 1.0 beta and was rolled back. Online docs default to 1.0 beta APIs that do NOT exist here. If typecheck complains, you are probably importing a 1.0 beta API.
-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)
+- Driver: `drizzle-orm/postgres-js`. Do NOT use `drizzle-orm/bun-sql`.
+- `drizzle()` is called with `{ connection, schema }` where `schema = import * as schema from '@/server/db/schema'`. There is **no `relations.ts`** and **no `defineRelations`** in 0.x.
+- Zod generators live in the separate `drizzle-zod` package (`^0.8.3`). Import from `drizzle-zod`, **not** `drizzle-orm/zod` (that subpath only exists in 1.0 beta).
+- Relational queries use **RQB v1 callback syntax**:
+  ```ts
+  db.query.todoTable.findMany({
+    orderBy: (t, { desc }) => desc(t.createdAt),
+  })
+  ```
+  Do NOT use the v2 object form (`orderBy: { createdAt: 'desc' }`, `where: { id }`) — it won't type-check.
+- To add relations later: declare per-table with `relations()` from `drizzle-orm` and export them from the same file as the table; they get picked up automatically because `index.ts` does `drizzle({ schema })` via `import *`.
+- Every table must spread `...generatedFields` from `src/server/db/fields.ts` (`id uuid PRIMARY KEY DEFAULT uuidv7() NOT NULL` — **Postgres-side generation**, requires PG18+; `createdAt`, `updatedAt` with `$onUpdateFn`). The DB is the single source of UUIDv7 truth: monotonic per cluster, uses DB clock, no app-side round-trip. **Do not reintroduce `$defaultFn(() => Bun.randomUUIDv7())`** — the SQL default is what the migration emits and what `drizzle-zod` reads as "optional in insert schema". `generatedFieldKeys` is hand-written and uses `satisfies Record<keyof typeof generatedFields, true>` so any field-key drift fails typecheck; it feeds `createInsertSchema(...).omit(...)` / `createUpdateSchema(...).omit(...)`.
+- `src/server/db/index.ts` exports a module-level `const db = drizzle(...)` — not a lazy singleton. On Bun this is a long-lived process, so top-level side effects are fine and requested. Don't reintroduce `getDB/closeDB` ceremony; the Nitro shutdown plugin calls `db.$client.end()` directly. (Cloudflare Workers would need per-request init — we don't support that deployment target.)
+- `drizzle.config.ts` runs outside Vite — `@/*` path aliases do NOT resolve there. It currently does `import { env } from './src/env'` (relative). Preserve that.
+- **Migrations are embedded in the binary, not read from disk.** `bun run db:generate` chains `drizzle-kit generate && bun scripts/embed-migrations.ts`, which regenerates `src/server/db/migrations.gen.ts` (committed, AUTO-GENERATED header) by `import sql_<idx> from '#drizzle/<tag>.sql' with { type: 'text' }`. `src/cli/migrate.ts` reads `embeddedMigrations`, **validates SHA-256 hash of every already-applied migration against the embedded SQL** (rejects schema drift if anyone edited an applied migration), then applies pending entries via `db.execute(sql\`...\`)` + `db.transaction(...)` against the `drizzle.__drizzle_migrations` book-keeping table — public APIs only, no `db.dialect`/`db.session` (those are `@internal`). Each migration is split on `--> statement-breakpoint`; empty fragments are trimmed and skipped. Dev helpers `db:push` / `drizzle-kit migrate` still read `./drizzle/`.
 
-### Formatting (Biome)
+## CLI & single-binary deploy
-- **Indent**: 2 spaces | **Line endings**: LF
-- **Quotes**: Single `'` | **Semicolons**: Omit (ASI)
-- **Arrow parentheses**: Always `(x) => x`
 
-### Imports
+`bun run compile` produces a single executable that dispatches subcommands via [citty](https://github.com/unjs/citty). Entry is `src/bin.ts`; subcommands live in `src/cli/`.
-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 v1 beta + postgres-js)
-
-- **ORM**: Drizzle ORM `1.0.0-beta` (RQBv2)
-- **Driver**: `drizzle-orm/postgres-js` (NOT `bun-sql`)
-- **Validation**: `drizzle-orm/zod` (built-in, NOT separate `drizzle-zod` package)
-- **Relations**: Defined via `defineRelations()` in `src/server/db/relations.ts` (contains schema info, so `drizzle()` only needs `{ relations }`)
-- **Query style**: RQBv2 object syntax (`orderBy: { createdAt: 'desc' }`, `where: { id: 1 }`)
-
-```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
-
-## Development Principles
-
-> **These principles apply to ALL code changes. Agents MUST follow them on every task.**
-
-1. **No backward compatibility** — This project is in rapid iteration. Always use the latest API and patterns. Never keep deprecated code paths or old API fallbacks "just in case".
-2. **Always sync documentation** — When code changes, immediately update all related documentation (`AGENTS.md`, `README.md`, inline code examples). Code and docs must never drift apart. This includes updating code snippets in docs when imports, APIs, or patterns change.
-3. **Forward-only migration** — When upgrading dependencies, fully adopt the new API. Don't mix old and new patterns in the same codebase.
-
-## Critical Rules
-
-**DO:**
-- Run `bun run fix` before committing
-- Use `@/*` path aliases (not relative imports)
-- Include `createdAt`/`updatedAt` on all tables
-- Use `catalog:` for dependency versions
-- Update `AGENTS.md` and other docs whenever code patterns change
-
-**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
-- Leave docs out of sync with code changes
-
-## Git Workflow
-
-1. Make changes following style guide
-2. `bun run fix` - auto-format and lint
-3. `bun run typecheck` - verify types
-4. `bun run dev` - test locally
-5. Commit with descriptive message
-
-## Directory Structure
 
 ```
-.
+./server [serve]   # default — start the HTTP server
-├── apps/
+./server migrate   # apply embedded migrations
-│   ├── server/           # TanStack Start fullstack app
+./server --help
-│   │   ├── src/
-│   │   │   ├── client/   # ORPC client + TanStack Query utils
-│   │   │   ├── components/
-│   │   │   ├── routes/   # File-based routing
-│   │   │   └── server/   # API layer + database
-│   │   │       ├── api/  # ORPC contracts, routers, middlewares
-│   │   │       └── db/   # Drizzle schema
-│   │   └── AGENTS.md
-│   └── desktop/          # Electron desktop shell
-│       ├── src/
-│       │   ├── main/
-│       │   │   └── index.ts       # Main process entry
-│       │   └── preload/
-│       │       └── index.ts       # Preload script
-│       ├── electron.vite.config.ts
-│       ├── electron-builder.yml   # Packaging config
-│       └── AGENTS.md
-├── packages/
-│   └── tsconfig/         # Shared TS configs
-├── biome.json            # Linting/formatting config
-├── turbo.json            # Turbo task orchestration
-└── package.json          # Workspace root + dependency catalog
 ```
 
-## See Also
+**Nitro side-effect pitfall (important).** Under the `bun` preset, `.output/server/index.mjs` has a top-level `serve(...)` call — merely importing it starts the HTTP server. `src/bin.ts` therefore must not eager-import any subcommand module, and `src/cli/serve.ts` reaches `.output/server/index.mjs` through the `src/cli/_serve-nitro.mjs` bridge (with `_serve-nitro.d.mts` for types, since `.output/` doesn't exist at typecheck time). Citty's `subCommands: { x: () => import('...') }` lazy-loader is what keeps `--help` and `migrate` from booting the server.
 
-- `apps/server/AGENTS.md` - Detailed TanStack Start / ORPC patterns
+**Citty eager-loads subcommand modules for `--help`** to read each subcommand's `meta`. So every `src/cli/*.ts` module body must be side-effect-free: do NOT static-import `@/env`, `@/server/db/*`, or anything that reads env at module-load time. Use `await import('@/env')` inside `run()`. Otherwise `./server --help` (or any subcommand's help) will fail with env validation errors before printing.
-- `apps/desktop/AGENTS.md` - Electron desktop development guide
+
+Add a subcommand: drop a file in `src/cli/` that default-exports `defineCommand({...})`, then register it in `src/bin.ts`'s `subCommands` with a `() => import(...)` thunk. Keep top-level imports limited to `citty` + Node built-ins; pull env / db / etc. via `await import(...)` inside `run()`.
+
+**Deploy flow is always migrate-then-serve.** Migrations are embedded in the binary (see "Drizzle" section), so the binary is the only artifact — no `./drizzle/` directory at runtime. Dockerfile copies just `./server`. `compose.yaml` models the pattern with a one-shot `migrate` service that `app` `depends_on: service_completed_successfully`. On k8s, run `./server migrate` as an initContainer or a Helm `pre-upgrade` Job; run `./server` (= `./server serve`) as the main container.
+
+## Compile flags
+
+`scripts/compile.ts` builds with `--minify --bytecode --sourcemap=inline`:
+
+- **`bytecode`** — pre-compiles JS to bytecode and embeds it in the binary; ~2x startup on app-sized binaries (Bun docs benchmark). Requires `--compile`; top-level `await` must live inside `async` functions (it already does in this repo).
+- **`minify`** — shrinks the binary and the bytecode it derives from.
+- **`sourcemap: 'inline'`** — embeds the source map in the binary so error stack traces stay decodable. Bun also writes a residual `out/bin.js.map` next to the output; `scripts/compile.ts` removes it so the binary is the only artifact.
+
+## ORPC
+
+Contract → Router → Handler → Client, all type-safe from a single contract.
+
+- `os` is built in `src/server/api/server.ts` via `implement(contract).$context<BaseContext>()`. **Always import `os` from `@/server/api/server`**, never from `@orpc/server` directly. `ORPCError`, `onError`, `ValidationError` come from `@orpc/server`.
+- Contracts (`src/server/api/contracts/*.contract.ts`) generate Zod from Drizzle tables via `drizzle-zod`:
+  ```ts
+  const insertSchema = createInsertSchema(todoTable).omit(generatedFieldKeys)
+  ```
+  Barrel-aggregated in `contracts/index.ts` as `export const contract = { todo }`.
+- Routers (`src/server/api/routers/*.router.ts`) import `db` directly from `@/server/db` in their handlers. There is **no `middlewares/` directory** by default — `db` doesn't need one (module-level const). When you actually need per-request context (auth, tenant, rate-limit), create `src/server/api/middlewares/<name>.middleware.ts` with `os.middleware(...)` and extend `BaseContext` in `context.ts`.
+- **Interceptors are attached at the handler level, not in `server.ts` and not on `os`.** Both `src/routes/api/rpc.$.ts` (`RPCHandler`) and `src/routes/api/$.ts` (`OpenAPIHandler`) register `[onError(logError)]` (server) and `[onError(handleValidationError)]` (client). The validation interceptor rewrites `BAD_REQUEST + ValidationError` into `INPUT_VALIDATION_FAILED` (422) and output validation errors into `OUTPUT_VALIDATION_FAILED`. `logError` resolves a `getLogger(['api'])` LogTape category — never `console.*` directly. See "Logging" section.
+- OpenAPI/Scalar: docs at `/api/docs`, spec at `/api/spec.json` (handler prefix `/api`, plugin paths `/docs` and `/spec.json`).
+- **SSR isomorphism** (`src/client/orpc.ts`): `createIsomorphicFn().server(createRouterClient(...)).client(new RPCLink(...))`. Server branch reads `getRequestHeaders()` for context; client branch POSTs to `${origin}/api/rpc`.
+- **Mutation invalidation is colocated at the call site** via `mutationOptions({ onSuccess })`, not in `src/client/orpc.ts`. `orpc` in `src/client/orpc.ts` is a plain `createTanstackQueryUtils(client)` — no `experimental_defaults`. Per-feature query helpers live in `src/client/queries/<feature>.ts` (e.g. `useInvalidateTodos`); routes/components compose those hooks rather than holding query keys inline. See `src/client/queries/todo.ts` + `src/routes/index.tsx` for the canonical shape.
+- SSR prefetch in route loaders: `await context.queryClient.ensureQueryData(orpc.todo.list.queryOptions())`. Components use `useSuspenseQuery(orpc.feature.list.queryOptions())`.
+
+## Code style (Biome)
+
+- 2-space, LF, single quotes, **semicolons as-needed** (omitted unless required), 120-col, arrow parens always, `useArrowFunction: "error"` (covers function *expressions* only). Also `noReactPropAssignments: "error"`.
+- Lint domains enabled (Biome 2.4): `types: "all"` (catches `noFloatingPromises`, `noMisusedPromises`, `useAwaitThenable`, `noUnnecessaryConditions` — TS-aware async/promise traps), `drizzle: "recommended"`, `react: "recommended"`. `noImportCycles` is on under `suspicious`.
+- **Route components use `function Foo()` declarations**, placed below the `Route` config so the file reads top-down (route on top, component below). This is the official TanStack Router/Start pattern and relies on hoisting — `const Foo = () => {}` would TDZ-error when referenced from `createFileRoute({ component: Foo })` above it. Inline arrows are fine for trivial leaf components (e.g. plain redirect routes). Non-route components (UI primitives in `src/components/`) use `const Foo = () => {}`.
+- Imports are auto-organized into two groups (external, then `@/*`), each alphabetical, with `import type` interleaved (NOT a separate group). `bun run fix` handles this; don't hand-sort.
+- Files: utils `kebab-case.ts`, components `PascalCase.tsx`.
+- `routeTree.gen.ts` is generated — ignored by Biome, never edit.
+
+## Testing
+
+`bun test` runs all `*.test.ts` files. Tests are colocated next to the source they exercise (e.g. `src/server/api/contracts/todo.contract.test.ts`). Use `import { describe, expect, test } from 'bun:test'`. The `@/*` alias resolves in tests via tsconfig paths. No Vitest, no Jest, no separate test config — keep it that way unless you need a browser/JSDOM environment.
+
+## Endpoints
+
+- `/` — Todos UI (file route).
+- `/health` — bare `GET` returning `ok` (200, `text/plain`). Liveness only — no DB check, so it stays green even when Postgres is down. Add a separate `/ready` if you ever need readiness.
+- `/api/rpc` — ORPC RPC handler (POST).
+- `/api/*` — ORPC OpenAPI handler. Docs at `/api/docs`, spec at `/api/spec.json`.
+
+## TypeScript
+
+Strict mode, plus `noUncheckedIndexedAccess`, `verbatimModuleSyntax`, `erasableSyntaxOnly`, `noImplicitOverride`. No `as any` / `@ts-ignore` / `@ts-expect-error`.
+
+Path alias: `@/* → src/*`. For files outside `src/` use `@/../<file>` (example in the codebase: `src/routes/api/$.ts` imports `name, version` from `@/../package.json`).
+
+## Env
+
+`src/env.ts` via `@t3-oss/env-core`. Server: `DATABASE_URL` (required, `z.url()`), `LOG_LEVEL` (`trace|debug|info|warning|error|fatal`, default `info`), `LOG_FORMAT` (`pretty|json`, default = TTY ? `pretty` : `json`), `LOG_DB` (`stringbool`, default `false` — flips on Drizzle SQL query logging). `client: {}` is empty by default — any client-side env must be `VITE_`-prefixed. Never commit `.env`.
+
+## Logging
+
+All server-side logging goes through `src/server/logger.ts`, a thin wrapper over [LogTape](https://logtape.org/). The module configures LogTape on import (via `configureSync`, no top-level await — works under `--bytecode`) and re-exports `getLogger`.
+
+```ts
+import { getLogger } from '@/server/logger'
+const logger = getLogger(['feature', 'subsystem'])
+logger.info('Created todo {id}', { id })
+logger.error('DB write failed', { error })
+```
+
+- Categories are hierarchical arrays — they show up as dot-paths in JSON output (`"logger":"feature.subsystem"`) and let you filter by prefix when shipping logs.
+- The `{name}` placeholders are for **primitive** values you want rendered inline (numbers, short strings, IDs). For objects, errors, and anything multi-field, omit the placeholder and just pass the value in properties — `logger.error('Auth failed', { error, userId })` keeps the message clean while properties stay structured. Never string-concatenate or template-literal — that defeats structured logging.
+- Format is `pretty` (icons + ANSI) on TTY, `json` (one-line JSON) when piped — perfect for Loki/Datadog/CloudWatch ingestion. Override with `LOG_FORMAT`.
+- Drizzle SQL queries are logged at `info` under category `['db']` when `LOG_DB=true`, via `@logtape/drizzle-orm`'s `DrizzleLogger` adapter (constructed in `src/server/db/index.ts`). The `info` level is intentional: flipping `LOG_DB=true` alone is enough — no need to also lower `LOG_LEVEL`.
+- `src/server/api/interceptors.ts` calls `getLogger(['api']).error(...)` from `logError`. CLI subcommands lazy-import the logger inside `run()` — they are still required to be side-effect-free at module top (citty eager-loads for `--help`).
+- Bun-specific: `process.env.NODE_ENV` is **inlined at build time** by `bun build --minify` — do NOT branch on it for logger config (use `process.stdout.isTTY` or `LOG_FORMAT` instead). pino is unusable here because its worker-thread transports crash inside the `/$bunfs/` virtual filesystem of compiled binaries; LogTape has zero workers and zero dynamic require, so it ships cleanly into the single binary.
+
+## Docker / deploy
+
+- Multi-stage: `oven/bun:1.3.13` builds and runs `bun scripts/compile.ts`, then `gcr.io/distroless/cc-debian13:nonroot` runs the single `./server` binary. The `cc` (glibc) distroless variant is required because Bun's compiled binary links glibc.
+- `compose.yaml`: one-shot `migrate` service runs `./server migrate` with `restart: "no"`, then `app` starts (`depends_on: migrate: service_completed_successfully`). `DATABASE_URL=postgres://postgres:postgres@db:5432/postgres` for both.
+- Distroless has no shell, so any init-then-serve pattern must use exec-form `command: [...]`, not `sh -c`.
+
+## Layout (non-obvious parts only)
+
+```
+src/
+├── bin.ts                      # citty entry — keep imports minimal (see "CLI" section)
+├── client/
+│   ├── orpc.ts                 # isomorphic ORPC client + TanStack Query utils (no global invalidation defaults)
+│   └── queries/                # per-feature query hooks: keys, options, `useInvalidate<Feature>` helpers
+├── cli/                        # CLI subcommands (loaded lazily by src/bin.ts via citty)
+│   ├── serve.ts                # `./server serve` — imports the Nitro bridge on demand
+│   ├── migrate.ts              # `./server migrate` — applies embedded migrations via public `db.execute(sql)` + `db.transaction()`
+│   ├── _serve-nitro.mjs        # bridge: `import('#server')` (subpath import → .output/server/index.mjs)
+│   └── _serve-nitro.d.mts      # types for the bridge (build output has no .d.ts)
+├── routes/
+│   ├── __root.tsx              # root route + RootDocument shell
+│   ├── index.tsx               # Todos UI
+│   ├── health.ts               # GET /health → "ok" (no DB)
+│   └── api/
+│       ├── $.ts                # OpenAPI + Scalar; interceptors registered here
+│       └── rpc.$.ts            # RPC; interceptors registered here
+├── server/
+│   ├── logger.ts               # LogTape `configureSync` + `getLogger` re-export — the only log entrypoint
+│   ├── api/
+│   │   ├── server.ts           # the ONLY place to build `os`
+│   │   ├── context.ts          # BaseContext (add per-request fields when you add middlewares)
+│   │   ├── interceptors.ts     # logError (→ logger), handleValidationError
+│   │   ├── types.ts            # Router{Client,Inputs,Outputs} derived from Contract
+│   │   ├── contracts/          # Zod schemas from Drizzle tables (barrel: contract); colocated *.test.ts
+│   │   └── routers/            # os.* handlers (barrel: router) — import db directly
+│   ├── db/
+│   │   ├── index.ts            # module-level `export const db = drizzle({...})`
+│   │   ├── fields.ts           # generatedFields (id/createdAt/updatedAt) + generatedFieldKeys
+│   │   ├── migrations.gen.ts   # AUTO-GENERATED by `bun run db:embed`; embeds ./drizzle/*.sql via `with { type: 'text' }`
+│   │   ├── sql.d.ts            # ambient `declare module '*.sql'` — load-bearing for `with { type: 'text' }` imports in migrations.gen.ts
+│   │   └── schema/             # pgTable definitions; also put `relations()` here when adding
+│   └── plugins/
+│       └── shutdown.ts         # SIGINT/SIGTERM → db.$client.end() with 500ms delay (prod only)
+├── components/                 # non-route UI primitives (PascalCase, arrow const)
+├── env.ts                      # t3-oss env validation
+├── router.tsx                  # QueryClient + setupRouterSsrQueryIntegration
+├── styles.css                  # Tailwind v4 entry
+└── routeTree.gen.ts            # auto-generated, do not edit
+scripts/
+├── compile.ts                  # `bun build --compile` driver; resolves --target; sets minify/bytecode/sourcemap
+└── embed-migrations.ts         # codegen: scans ./drizzle/meta/_journal.json → src/server/db/migrations.gen.ts
+drizzle/                        # SQL migrations (source of truth for `db:generate`; not shipped in binary)
+```
+
+Nitro plugins are wired in `vite.config.ts` (`nitro({ plugins: [...] })`), not via a Nitro config file.
+
+## Don'ts (specific, non-obvious)
+
+- **Don't run `bun run db:generate` (or `drizzle-kit generate`) as an AI agent.** Migration generation is reserved for the human. Make schema changes in `src/server/db/schema/*` + `src/server/db/fields.ts`, push the code changes, and stop — the human will run `bun run db:generate` and commit the resulting `drizzle/*.sql` + `src/server/db/migrations.gen.ts` themselves. (`bun run db:embed` is also off-limits because it's the codegen tail of `db:generate`.)
+- Don't edit `routeTree.gen.ts` or `src/server/db/migrations.gen.ts`.
+- Don't eager-import anything from `.output/` in `src/bin.ts` or any module it statically imports — it starts the HTTP server as a side effect. Subcommands must be lazy via citty's `() => import(...)` thunks.
+- Don't re-add an auto-migrate Nitro plugin. Migrations are an explicit deploy step via `./server migrate`.
+- Don't reach into `db.dialect`/`db.session` from `migrate.ts` — they're `@internal`. The current implementation uses public `db.execute(sql)` + `db.transaction(...)` against the documented `drizzle.__drizzle_migrations` schema.
+- Don't add `./drizzle/` back to the runtime image — migrations are embedded into the binary.
+- Don't reintroduce `getDB/closeDB` or any "lazy DB init" pattern — that's a Cloudflare Workers shape; we deploy on Bun processes.
+- Don't import `os` from `@orpc/server` in middleware/routers — always `@/server/api/server`.
+- Don't import from `drizzle-orm/zod` (1.0 beta only). Use `drizzle-zod`.
+- Don't use RQB v2 object syntax, `defineRelations`, or pass `relations` to `drizzle()`. All are 1.0 beta.
+- Don't use `drizzle-orm/bun-sql`.
+- Don't use `@/*` aliases in `drizzle.config.ts`.
+- Don't commit `.env`.
+
+## Room-to-grow rules (discipline for the first real feature)
+
+These keep the starter from setting bad precedents as it grows. Append, don't restructure.
+
+1. Per-feature client query code — keys, options, `useInvalidate<Feature>` helpers — lives in `src/client/queries/<feature>.ts`. Routes/components compose these hooks; they don't hold query keys inline.
+2. Mutation invalidation stays explicit at the mutation call site (`mutationOptions({ onSuccess })`) or in a feature query helper. Do not reintroduce global `experimental_defaults` or any implicit cache policy.
+3. Client state defaults to route/component local state. Create a store (zustand or equivalent) only when state is shared across routes or needs persistence.
+4. Middlewares (`src/server/api/middlewares/<name>.middleware.ts`) derive request-scoped context or gate access. They do NOT orchestrate business flow, hold side effects, or replace handlers/services.
+5. Interceptors (`src/server/api/interceptors.ts`) do cross-cutting error logging, transport normalization, and validation rewrites. They do NOT read business data.
+6. One file per Drizzle table. Relations live in the same file and are exported as `<entity>Relations`. No global `relations.ts`.
+7. One router file per feature (`routers/<feature>.router.ts`). Only introduce `routers/<domain>/index.ts` when a domain grows past ~5 router files or needs shared domain helpers.
+8. All server-side logging goes through `getLogger([...])` from `@/server/logger`. Use a hierarchical category (`['api']`, `['db']`, `['cli', 'migrate']`, etc.) — these become dot-paths in JSON output and let you filter by prefix. Use the `{name}` placeholder + properties form, not string interpolation. `console.*` is forbidden in business code.
+9. CLI subcommand modules keep top-level imports to `citty` + Node built-ins. Env, db, and server code are `await import(...)`-ed inside `run()` (see `src/bin.ts` comment for why).
+10. Every new business feature ships with at least one `bun test` covering a contract schema, a pure helper, or a router behavior.

Dockerfile

@@ -0,0 +1,21 @@
+FROM oven/bun:1.3.13 AS build
+
+WORKDIR /app
+
+COPY package.json bun.lock ./
+RUN bun install --frozen-lockfile
+
+COPY . .
+RUN bun run build \
+    && bun run compile \
+    && mv out/server-* out/server
+
+FROM gcr.io/distroless/cc-debian13:nonroot
+
+WORKDIR /app
+COPY --from=build --chown=nonroot:nonroot /app/out/server ./server
+
+ENV HOST=0.0.0.0
+EXPOSE 3000
+
+CMD ["./server"]

README.md

@@ -0,0 +1,112 @@
+# fullstack-starter
+
+一个**单二进制**的全栈应用 starter——`bun run compile` 出来的 `./server` 文件就是你要部署的全部产物，自带 HTTP 服务、SSR、API、嵌入式 SQL 迁移，运行时不依赖 Node、不依赖源码、不依赖外部 migration 目录。
+
+技术栈：Bun · TanStack Start (React 19 SSR) · ORPC（契约优先 API）· Drizzle ORM · PostgreSQL 18+ · Tailwind v4 · Biome。
+
+## 为什么用这个
+
+- **部署最简**：发布只拷一个二进制文件。先 `./server migrate` 再 `./server`，完事。
+- **契约优先**：在 `*.contract.ts` 用 Zod 定义一次，前端、后端、OpenAPI 文档自动同步。
+- **类型严格**：TypeScript strict，杜绝 `any` / `@ts-ignore` / `as any` 等类型逃逸。
+- **开箱可跑**：路径别名、文件路由、ORPC 接线、Tailwind、热重载、错误页全部预接好。
+
+## 快速开始
+
+> **需要 PostgreSQL 18+**——schema 用 PG 原生的 `uuidv7()` 生成主键（`compose.yaml` 已锁 `postgres:18-alpine`）。要兼容更老的 PG，把 `src/server/db/fields.ts` 里的 `default(sql\`uuidv7()\`)` 换成 `$defaultFn(() => Bun.randomUUIDv7())`，再跑 `bun run db:generate`。
+
+```bash
+cp .env.example .env        # 把里面的 DATABASE_URL 改成你的 Postgres
+bun install
+bun run db:push             # 开发期：把 schema 直接同步到 DB（不写 migration 文件）
+bun run dev                 # http://localhost:3000
+```
+
+打开浏览器：
+
+- `http://localhost:3000/` — Todo 示例页
+- `http://localhost:3000/api/docs` — Scalar 渲染的 API 文档
+
+## 目录结构（你需要关心的部分）
+
+```
+src/
+├── routes/                 # 文件路由：页面 + API 端点
+├── server/
+│   ├── api/
+│   │   ├── contracts/      # Zod 契约（client / server 共享）
+│   │   └── routers/        # 业务实现
+│   └── db/                 # Drizzle schema + 嵌入式 migrations
+├── client/                 # 前端 hooks、ORPC 客户端
+└── components/             # UI 组件
+```
+
+## 加一个功能（以 `post` 为例）
+
+每一步都很短，按顺序填即可：
+
+1. **建表**：`src/server/db/schema/post.ts` 定义 `postTable`，记得展开 `...generatedFields`（自动注入 `id` / `createdAt` / `updatedAt`）。
+2. **导出表**：在 `src/server/db/schema/index.ts` 加 `export * from './post'`。
+3. **写契约**：`src/server/api/contracts/post.contract.ts` 用 `drizzle-zod` 从表派生 Zod schema。
+4. **挂契约**：在 `src/server/api/contracts/index.ts` 把 `post` 加进 `contract` 对象。
+5. **写实现**：`src/server/api/routers/post.router.ts` 实现 `os.post.*.handler(...)`。
+6. **挂路由**：在 `src/server/api/routers/index.ts` 把 `post` 加进 `router` 对象。
+7. **写前端 hook**：`src/client/queries/post.ts` 导出 `useInvalidatePosts` 等失效辅助。
+8. **写页面**：`src/routes/<page>.tsx` 用 `useSuspenseQuery` 读、`mutate` 写；mutation 的 `onSuccess` 调用第 7 步的 helper。
+9. **生成 migration**：`bun run db:generate` 把 SQL 写到 `./drizzle/` 并嵌入二进制。
+
+完工。`bun run dev` 已自动热重载。
+
+## 部署
+
+**永远先 migrate 再 serve**。Migration 已嵌入二进制；部署只发一个 `./server` 文件。
+
+```bash
+./server migrate            # 应用嵌入式 migration（用 $DATABASE_URL）
+./server                    # 启动 HTTP 服务（默认子命令）
+./server --help             # 列出所有子命令
+```
+
+仓库自带 `compose.yaml`（一次性 `migrate` 服务先跑完，再启动 `app`）：
+
+```bash
+docker compose up --build
+```
+
+Kubernetes 上：把 `./server migrate` 放进 initContainer 或 Helm `pre-upgrade` Job，主容器跑 `./server`。
+
+## 脚本一览
+
+| 命令 | 作用 |
+| --- | --- |
+| `bun run dev` | Vite 开发服务器（默认端口 3000） |
+| `bun run build` | 构建到 `.output/`（`bun run compile` 会用到） |
+| `bun run compile` | 生成单二进制 `out/server-<target>` |
+| `bun run typecheck` | TypeScript 类型检查 |
+| `bun run test` | 运行所有 `*.test.ts` |
+| `bun run fix` | Biome 格式化 + lint + 整理 imports |
+| `bun run db:push` | 开发期：直接同步 schema 到 DB（不写 migration 文件） |
+| `bun run db:generate` | 写 SQL migration 到 `./drizzle/` 并嵌入二进制 |
+| `bun run db:embed` | 仅重生 `migrations.gen.ts`（手改了 `./drizzle/*.sql` 后用） |
+| `bun run db:migrate` | 通过 drizzle-kit 在本地应用 migration（开发便利） |
+| `bun run db:studio` | Drizzle Studio（可视化 DB） |
+
+跨平台编译：`bun run compile:{linux,darwin,windows}[:arch]`。
+
+## 端点
+
+| 路径 | 用途 |
+| --- | --- |
+| `/` | Todo 示例 UI |
+| `/health` | 存活探针（不查 DB，纯文本 `ok`） |
+| `/api/rpc` | ORPC RPC 端点（client 直连） |
+| `/api/docs` | Scalar 渲染的 API 文档 |
+| `/api/spec.json` | OpenAPI spec |
+
+## 提交前
+
+```bash
+bun run fix && bun run typecheck && bun run test
+```
+
+没有 CI、没有 pre-commit hook——上面三条由你自觉跑。

apps/desktop/.gitignore

@@ -1,3 +0,0 @@
-# electron-vite build output
-out/
-dist/

apps/desktop/AGENTS.md

@@ -1,95 +0,0 @@
-# AGENTS.md - Desktop App Guidelines
-
-Thin Electron shell hosting the fullstack server app.
-
-## Tech Stack
-
-> **⚠️ This project uses Bun as the package manager. Runtime is Electron (Node.js). Always use `bun run <script>` (not `bun <script>`) to avoid conflicts with Bun built-in subcommands. Never use `npm`, `npx`, `yarn`, or `pnpm`.**
-
-- **Type**: Electron desktop shell
-- **Design**: Server-driven desktop (thin native window hosting web app)
-- **Runtime**: Electron (Main/Renderer) + Sidecar server binary (Bun-compiled)
-- **Build Tool**: electron-vite (Vite-based, handles main + preload builds)
-- **Packager**: electron-builder (installers, signing, auto-update)
-- **Orchestration**: Turborepo
-
-## Architecture
-
-- **Server-driven design**: The desktop app is a "thin" native shell. It does not contain UI or business logic; it opens a BrowserWindow pointing to the `apps/server` TanStack Start application.
-- **Dev mode**: Opens a BrowserWindow pointing to `localhost:3000`. Requires `apps/server` to be running separately (Turbo handles this).
-- **Production mode**: Spawns a compiled server binary (from `resources/`) as a sidecar process, waits for readiness, then loads its URL.
-
-## Commands
-
-```bash
-bun run dev                    # electron-vite dev (requires server dev running)
-bun run build                  # electron-vite build (main + preload)
-bun run dist                   # Build + package for current platform
-bun run dist:linux             # Build + package for Linux (x64 + arm64)
-bun run dist:linux:x64         # Build + package for Linux x64
-bun run dist:linux:arm64       # Build + package for Linux arm64
-bun run dist:mac               # Build + package for macOS (arm64 + x64)
-bun run dist:mac:arm64         # Build + package for macOS arm64
-bun run dist:mac:x64           # Build + package for macOS x64
-bun run dist:win               # Build + package for Windows x64
-bun run fix                    # Biome auto-fix
-bun run typecheck              # TypeScript check
-```
-
-## Directory Structure
-
-```
-.
-├── src/
-│   ├── main/
-│   │   └── index.ts       # Main process (server lifecycle + BrowserWindow)
-│   └── preload/
-│       └── index.ts       # Preload script (security isolation)
-├── resources/             # Sidecar binaries (gitignored, copied from server build)
-├── out/                   # electron-vite build output (gitignored)
-├── electron.vite.config.ts
-├── electron-builder.yml   # Packaging configuration
-├── package.json
-├── turbo.json
-└── AGENTS.md
-```
-
-## Development Workflow
-
-1. **Start server**: `bun run dev` in `apps/server` (or use root `bun run dev` via Turbo).
-2. **Start desktop**: `bun run dev` in `apps/desktop`.
-3. **Connection**: Main process polls `localhost:3000` until responsive, then opens BrowserWindow.
-
-## Production Build Workflow
-
-From monorepo root, run `bun run dist` to execute the full pipeline automatically (via Turbo task dependencies):
-
-1. **Build server**: `apps/server` → `vite build` → `.output/`
-2. **Compile server**: `apps/server` → `bun compile.ts --target ...` → `out/server-{os}-{arch}`
-3. **Package desktop**: `apps/desktop` → `electron-vite build` + `electron-builder` → distributable
-
-The `electron-builder.yml` `extraResources` config reads binaries directly from `../server/out/`, no manual copy needed.
-
-To build for a specific platform explicitly, use `bun run dist:linux` / `bun run dist:mac` / `bun run dist:win` in `apps/desktop`.
-For single-arch output, use `bun run dist:linux:x64`, `bun run dist:linux:arm64`, `bun run dist:mac:x64`, or `bun run dist:mac:arm64`.
-
-## Development Principles
-
-> **These principles apply to ALL code changes. Agents MUST follow them on every task.**
-
-1. **No backward compatibility** — This project is in rapid iteration. Always use the latest API and patterns. Never keep deprecated code paths or old API fallbacks.
-2. **Always sync documentation** — When code changes, immediately update all related documentation (`AGENTS.md`, `README.md`, inline code examples). Code and docs must never drift apart.
-3. **Forward-only migration** — When upgrading dependencies, fully adopt the new API. Don't mix old and new patterns.
-
-## Critical Rules
-
-**DO:**
-- Use arrow functions for all utility functions.
-- Keep the desktop app as a thin shell — no UI or business logic.
-- Use `catalog:` for all dependency versions in `package.json`.
-
-**DON'T:**
-- Use `npm`, `npx`, `yarn`, or `pnpm`. Use `bun` for package management.
-- Include UI components or business logic in the desktop app.
-- Use `as any` or `@ts-ignore`.
-- Leave docs out of sync with code changes.

apps/desktop/biome.json

@@ -1,9 +0,0 @@
-{
-  "$schema": "../../node_modules/@biomejs/biome/configuration_schema.json",
-  "extends": "//",
-  "css": {
-    "parser": {
-      "tailwindDirectives": true
-    }
-  }
-}

apps/desktop/electron-builder.yml

@@ -1,48 +0,0 @@
-# yaml-language-server: $schema=https://raw.githubusercontent.com/electron-userland/electron-builder/refs/heads/master/packages/app-builder-lib/scheme.json
-appId: com.furtherverse.desktop
-productName: Furtherverse
-executableName: furtherverse
-
-npmRebuild: false
-asarUnpack:
-  - resources/**
-
-files:
-  - "!**/.vscode/*"
-  - "!src/*"
-  - "!electron.vite.config.{js,ts,mjs,cjs}"
-  - "!{.env,.env.*,bun.lock}"
-  - "!{tsconfig.json,tsconfig.node.json}"
-  - "!{AGENTS.md,README.md,CHANGELOG.md}"
-
-# macOS
-mac:
-  target:
-    - dmg
-  category: public.app-category.productivity
-  extraResources:
-    - from: ../server/out/server-darwin-${arch}
-      to: server
-dmg:
-  artifactName: ${productName}-${version}-${os}-${arch}.${ext}
-
-# Windows
-win:
-  target:
-    - portable
-  extraResources:
-    - from: ../server/out/server-windows-${arch}.exe
-      to: server.exe
-portable:
-  artifactName: ${productName}-${version}-${os}-${arch}-Portable.${ext}
-
-# Linux
-linux:
-  target:
-    - AppImage
-  category: Utility
-  extraResources:
-    - from: ../server/out/server-linux-${arch}
-      to: server
-appImage:
-  artifactName: ${productName}-${version}-${os}-${arch}.${ext}

apps/desktop/electron.vite.config.ts

@@ -1,11 +0,0 @@
-import tailwindcss from '@tailwindcss/vite'
-import react from '@vitejs/plugin-react'
-import { defineConfig } from 'electron-vite'
-
-export default defineConfig({
-  main: {},
-  preload: {},
-  renderer: {
-    plugins: [react(), tailwindcss()],
-  },
-})

apps/desktop/package.json

@@ -1,37 +0,0 @@
-{
-  "name": "@furtherverse/desktop",
-  "version": "1.0.0",
-  "private": true,
-  "main": "out/main/index.js",
-  "scripts": {
-    "build": "electron-vite build",
-    "dev": "electron-vite dev --watch",
-    "dist": "electron-builder",
-    "dist:linux": "bun run dist:linux:x64 && bun run dist:linux:arm64",
-    "dist:linux:arm64": "electron-builder --linux --arm64",
-    "dist:linux:x64": "electron-builder --linux --x64",
-    "dist:mac": "bun run dist:mac:arm64 && bun run dist:mac:x64",
-    "dist:mac:arm64": "electron-builder --mac --arm64",
-    "dist:mac:x64": "electron-builder --mac --x64",
-    "dist:win": "electron-builder --win --x64",
-    "fix": "biome check --write",
-    "typecheck": "tsc -b"
-  },
-  "dependencies": {
-    "motion": "catalog:",
-    "react": "catalog:",
-    "react-dom": "catalog:",
-    "tree-kill": "catalog:"
-  },
-  "devDependencies": {
-    "@furtherverse/tsconfig": "workspace:*",
-    "@tailwindcss/vite": "catalog:",
-    "@types/node": "catalog:",
-    "@vitejs/plugin-react": "catalog:",
-    "electron": "catalog:",
-    "electron-builder": "catalog:",
-    "electron-vite": "catalog:",
-    "tailwindcss": "catalog:",
-    "vite": "catalog:"
-  }
-}

apps/desktop/src/main/index.ts

@@ -1,198 +0,0 @@
-import { join } from 'node:path'
-import { app, BrowserWindow, dialog, session, shell } from 'electron'
-import { createSidecarRuntime } from './sidecar'
-
-const DEV_SERVER_URL = 'http://localhost:3000'
-const SAFE_EXTERNAL_PROTOCOLS = new Set(['https:', 'http:', 'mailto:'])
-
-let mainWindow: BrowserWindow | null = null
-let windowCreationPromise: Promise<void> | null = null
-let isQuitting = false
-
-const showErrorAndQuit = (title: string, detail: string) => {
-  if (isQuitting) {
-    return
-  }
-
-  dialog.showErrorBox(title, detail)
-  app.quit()
-}
-
-const sidecar = createSidecarRuntime({
-  devServerUrl: DEV_SERVER_URL,
-  isPackaged: app.isPackaged,
-  resourcesPath: process.resourcesPath,
-  isQuitting: () => isQuitting,
-  onUnexpectedStop: (detail) => {
-    showErrorAndQuit('Service Stopped', detail)
-  },
-})
-
-const toErrorMessage = (error: unknown): string => (error instanceof Error ? error.message : String(error))
-
-const canOpenExternally = (url: string): boolean => {
-  try {
-    const parsed = new URL(url)
-    return SAFE_EXTERNAL_PROTOCOLS.has(parsed.protocol)
-  } catch {
-    return false
-  }
-}
-
-const loadSplash = async (windowRef: BrowserWindow) => {
-  if (process.env.ELECTRON_RENDERER_URL) {
-    await windowRef.loadURL(process.env.ELECTRON_RENDERER_URL)
-    return
-  }
-
-  await windowRef.loadFile(join(__dirname, '../renderer/index.html'))
-}
-
-const createWindow = async () => {
-  if (mainWindow && !mainWindow.isDestroyed()) {
-    mainWindow.focus()
-    return
-  }
-
-  const windowRef = new BrowserWindow({
-    width: 1200,
-    height: 800,
-    show: false,
-    webPreferences: {
-      preload: join(__dirname, '../preload/index.js'),
-      sandbox: true,
-      contextIsolation: true,
-      nodeIntegration: false,
-    },
-  })
-  mainWindow = windowRef
-
-  windowRef.webContents.setWindowOpenHandler(({ url }) => {
-    if (!canOpenExternally(url)) {
-      if (!app.isPackaged) {
-        console.warn(`Blocked external URL: ${url}`)
-      }
-
-      return { action: 'deny' }
-    }
-
-    void shell.openExternal(url)
-    return { action: 'deny' }
-  })
-
-  windowRef.webContents.on('will-navigate', (event, url) => {
-    const allowed = [DEV_SERVER_URL, sidecar.lastResolvedUrl].filter((v): v is string => v != null)
-    const isAllowed = allowed.some((origin) => url.startsWith(origin))
-
-    if (!isAllowed) {
-      event.preventDefault()
-
-      if (canOpenExternally(url)) {
-        void shell.openExternal(url)
-      } else if (!app.isPackaged) {
-        console.warn(`Blocked navigation to: ${url}`)
-      }
-    }
-  })
-
-  windowRef.on('closed', () => {
-    if (mainWindow === windowRef) {
-      mainWindow = null
-    }
-  })
-
-  try {
-    await loadSplash(windowRef)
-  } catch (error) {
-    if (mainWindow === windowRef) {
-      mainWindow = null
-    }
-
-    if (!windowRef.isDestroyed()) {
-      windowRef.destroy()
-    }
-
-    throw error
-  }
-
-  if (!windowRef.isDestroyed()) {
-    windowRef.show()
-  }
-
-  const targetUrl = await sidecar.resolveUrl()
-  if (isQuitting || windowRef.isDestroyed()) {
-    return
-  }
-
-  try {
-    await windowRef.loadURL(targetUrl)
-  } catch (error) {
-    if (mainWindow === windowRef) {
-      mainWindow = null
-    }
-
-    if (!windowRef.isDestroyed()) {
-      windowRef.destroy()
-    }
-
-    throw error
-  }
-}
-
-const ensureWindow = async () => {
-  if (windowCreationPromise) {
-    return windowCreationPromise
-  }
-
-  windowCreationPromise = createWindow().finally(() => {
-    windowCreationPromise = null
-  })
-
-  return windowCreationPromise
-}
-
-const beginQuit = () => {
-  isQuitting = true
-  sidecar.stop()
-}
-
-const handleWindowCreationError = (error: unknown, context: string) => {
-  console.error(`${context}:`, error)
-  showErrorAndQuit(
-    "App Couldn't Start",
-    app.isPackaged
-      ? 'A required component failed to start. Please reinstall the app.'
-      : `${context}: ${toErrorMessage(error)}`,
-  )
-}
-
-app
-  .whenReady()
-  .then(() => {
-    session.defaultSession.setPermissionRequestHandler((_webContents, _permission, callback) => {
-      callback(false)
-    })
-
-    return ensureWindow()
-  })
-  .catch((error) => {
-    handleWindowCreationError(error, 'Failed to create window')
-  })
-
-app.on('window-all-closed', () => {
-  if (process.platform !== 'darwin') {
-    app.quit()
-  }
-})
-
-app.on('activate', () => {
-  if (isQuitting || BrowserWindow.getAllWindows().length > 0) {
-    return
-  }
-
-  ensureWindow().catch((error) => {
-    handleWindowCreationError(error, 'Failed to re-create window')
-  })
-})
-
-app.on('before-quit', beginQuit)

apps/desktop/src/main/sidecar.ts

@@ -1,256 +0,0 @@
-import { type ChildProcess, spawn } from 'node:child_process'
-import { existsSync } from 'node:fs'
-import { createServer } from 'node:net'
-import { join } from 'node:path'
-import killProcessTree from 'tree-kill'
-
-const SERVER_HOST = '127.0.0.1'
-const SERVER_READY_TIMEOUT_MS = 10_000
-const SERVER_REQUEST_TIMEOUT_MS = 1_500
-const SERVER_POLL_INTERVAL_MS = 250
-const SERVER_PROBE_PATHS = ['/api/health', '/']
-
-type SidecarState = {
-  process: ChildProcess | null
-  startup: Promise<string> | null
-  url: string | null
-}
-
-type SidecarRuntimeOptions = {
-  devServerUrl: string
-  isPackaged: boolean
-  resourcesPath: string
-  isQuitting: () => boolean
-  onUnexpectedStop: (detail: string) => void
-}
-
-type SidecarRuntime = {
-  resolveUrl: () => Promise<string>
-  stop: () => void
-  lastResolvedUrl: string | null
-}
-
-const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms))
-
-const isProcessAlive = (processToCheck: ChildProcess | null): processToCheck is ChildProcess => {
-  if (!processToCheck || !processToCheck.pid) {
-    return false
-  }
-
-  return processToCheck.exitCode === null && !processToCheck.killed
-}
-
-const getAvailablePort = (): Promise<number> =>
-  new Promise((resolve, reject) => {
-    const server = createServer()
-    server.listen(0, () => {
-      const addr = server.address()
-      if (!addr || typeof addr === 'string') {
-        server.close()
-        reject(new Error('Failed to resolve port'))
-        return
-      }
-
-      server.close(() => resolve(addr.port))
-    })
-    server.on('error', reject)
-  })
-
-const isServerReady = async (url: string): Promise<boolean> => {
-  for (const probePath of SERVER_PROBE_PATHS) {
-    try {
-      const probeUrl = new URL(probePath, `${url}/`)
-      const response = await fetch(probeUrl, {
-        method: 'GET',
-        cache: 'no-store',
-        signal: AbortSignal.timeout(SERVER_REQUEST_TIMEOUT_MS),
-      })
-
-      if (response.status < 500) {
-        if (probePath === '/api/health' && response.status === 404) {
-          continue
-        }
-
-        return true
-      }
-    } catch {
-      // Expected: probe request fails while server is still starting up
-    }
-  }
-
-  return false
-}
-
-const waitForServer = async (url: string, isQuitting: () => boolean, processRef?: ChildProcess): Promise<boolean> => {
-  const start = Date.now()
-  while (Date.now() - start < SERVER_READY_TIMEOUT_MS && !isQuitting()) {
-    if (processRef && processRef.exitCode !== null) {
-      return false
-    }
-
-    if (await isServerReady(url)) {
-      return true
-    }
-
-    await sleep(SERVER_POLL_INTERVAL_MS)
-  }
-
-  return false
-}
-
-const resolveBinaryPath = (resourcesPath: string): string => {
-  const binaryName = process.platform === 'win32' ? 'server.exe' : 'server'
-  return join(resourcesPath, binaryName)
-}
-
-const formatUnexpectedStopMessage = (
-  isPackaged: boolean,
-  code: number | null,
-  signal: NodeJS.Signals | null,
-): string => {
-  if (isPackaged) {
-    return 'The background service stopped unexpectedly. Please restart the app.'
-  }
-
-  return `Server process exited unexpectedly (code ${code ?? 'unknown'}, signal ${signal ?? 'none'}).`
-}
-
-export const createSidecarRuntime = (options: SidecarRuntimeOptions): SidecarRuntime => {
-  const state: SidecarState = {
-    process: null,
-    startup: null,
-    url: null,
-  }
-
-  const resetState = (processRef?: ChildProcess) => {
-    if (processRef && state.process !== processRef) {
-      return
-    }
-
-    state.process = null
-    state.url = null
-  }
-
-  const stop = () => {
-    const runningServer = state.process
-    resetState()
-
-    if (!runningServer?.pid || runningServer.exitCode !== null) {
-      return
-    }
-
-    killProcessTree(runningServer.pid, 'SIGTERM', (error?: Error) => {
-      if (error) {
-        console.error('Failed to stop server process:', error)
-      }
-    })
-  }
-
-  const attachLifecycleHandlers = (processRef: ChildProcess) => {
-    processRef.on('error', (error) => {
-      if (state.process !== processRef) {
-        return
-      }
-
-      const hadReadyServer = state.url !== null
-      resetState(processRef)
-
-      if (!options.isQuitting() && hadReadyServer) {
-        options.onUnexpectedStop('The background service crashed unexpectedly. Please restart the app.')
-        return
-      }
-
-      console.error('Failed to start server process:', error)
-    })
-
-    processRef.on('exit', (code, signal) => {
-      if (state.process !== processRef) {
-        return
-      }
-
-      const hadReadyServer = state.url !== null
-      resetState(processRef)
-
-      if (!options.isQuitting() && hadReadyServer) {
-        options.onUnexpectedStop(formatUnexpectedStopMessage(options.isPackaged, code, signal))
-      }
-    })
-  }
-
-  const startPackagedServer = async (): Promise<string> => {
-    if (state.url && isProcessAlive(state.process)) {
-      return state.url
-    }
-
-    if (state.startup) {
-      return state.startup
-    }
-
-    state.startup = (async () => {
-      const binaryPath = resolveBinaryPath(options.resourcesPath)
-      if (!existsSync(binaryPath)) {
-        throw new Error(`Sidecar server binary is missing: ${binaryPath}`)
-      }
-
-      if (options.isQuitting()) {
-        throw new Error('Application is shutting down.')
-      }
-
-      const port = await getAvailablePort()
-      const nextServerUrl = `http://${SERVER_HOST}:${port}`
-      const processRef = spawn(binaryPath, [], {
-        env: {
-          ...process.env,
-          HOST: SERVER_HOST,
-          PORT: String(port),
-        },
-        stdio: 'ignore',
-        windowsHide: true,
-      })
-
-      processRef.unref()
-      state.process = processRef
-      attachLifecycleHandlers(processRef)
-
-      const ready = await waitForServer(nextServerUrl, options.isQuitting, processRef)
-      if (ready && isProcessAlive(processRef)) {
-        state.url = nextServerUrl
-        return nextServerUrl
-      }
-
-      const failureReason =
-        processRef.exitCode !== null
-          ? `The service exited early (code ${processRef.exitCode}).`
-          : `The service did not respond at ${nextServerUrl} within 10 seconds.`
-
-      stop()
-      throw new Error(failureReason)
-    })().finally(() => {
-      state.startup = null
-    })
-
-    return state.startup
-  }
-
-  const resolveUrl = async (): Promise<string> => {
-    if (options.isPackaged) {
-      return startPackagedServer()
-    }
-
-    const ready = await waitForServer(options.devServerUrl, options.isQuitting)
-    if (!ready) {
-      throw new Error('Dev server not responding. Run `bun dev` in apps/server first.')
-    }
-
-    state.url = options.devServerUrl
-    return options.devServerUrl
-  }
-
-  return {
-    resolveUrl,
-    stop,
-    get lastResolvedUrl() {
-      return state.url
-    },
-  }
-}

apps/desktop/src/preload/index.ts

@@ -1 +0,0 @@
-export {}

apps/desktop/src/renderer/components/SplashApp.tsx

@@ -1,33 +0,0 @@
-import { motion } from 'motion/react'
-import logoImage from '../assets/logo.png'
-
-export const SplashApp = () => {
-  return (
-    <main className="m-0 flex h-screen w-screen cursor-default select-none items-center justify-center overflow-hidden bg-white font-sans antialiased">
-      <motion.section
-        animate={{ opacity: 1, y: 0 }}
-        className="flex flex-col items-center gap-8"
-        initial={{ opacity: 0, y: 4 }}
-        transition={{
-          duration: 1,
-          ease: [0.16, 1, 0.3, 1],
-        }}
-      >
-        <img alt="Logo" className="h-20 w-auto object-contain" draggable={false} src={logoImage} />
-
-        <div className="relative h-[4px] w-36 overflow-hidden rounded-full bg-zinc-100">
-          <motion.div
-            animate={{ x: '100%' }}
-            className="h-full w-full bg-zinc-800"
-            initial={{ x: '-100%' }}
-            transition={{
-              duration: 2,
-              ease: [0.4, 0, 0.2, 1],
-              repeat: Infinity,
-            }}
-          />
-        </div>
-      </motion.section>
-    </main>
-  )
-}

apps/desktop/src/renderer/index.html

@@ -1,12 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Furtherverse</title>
-  </head>
-  <body>
-    <div id="root"></div>
-    <script type="module" src="./main.tsx"></script>
-  </body>
-</html>

apps/desktop/src/renderer/main.tsx

@@ -1,11 +0,0 @@
-import { StrictMode } from 'react'
-import { createRoot } from 'react-dom/client'
-import { SplashApp } from './components/SplashApp'
-import './styles.css'
-
-// biome-ignore lint/style/noNonNullAssertion: 一定存在
-createRoot(document.getElementById('root')!).render(
-  <StrictMode>
-    <SplashApp />
-  </StrictMode>,
-)

apps/desktop/tsconfig.app.json

@@ -1,8 +0,0 @@
-{
-  "extends": "@furtherverse/tsconfig/react.json",
-  "compilerOptions": {
-    "composite": true,
-    "types": ["vite/client"]
-  },
-  "include": ["src/renderer/**/*"]
-}

apps/desktop/tsconfig.json

@@ -1,11 +0,0 @@
-{
-  "files": [],
-  "references": [
-    {
-      "path": "./tsconfig.app.json"
-    },
-    {
-      "path": "./tsconfig.node.json"
-    }
-  ]
-}

apps/desktop/tsconfig.node.json

@@ -1,8 +0,0 @@
-{
-  "extends": "@furtherverse/tsconfig/base.json",
-  "compilerOptions": {
-    "composite": true,
-    "types": ["node"]
-  },
-  "include": ["src/main/**/*", "src/preload/**/*", "electron.vite.config.ts"]
-}

apps/desktop/turbo.json

@@ -1,41 +0,0 @@
-{
-  "$schema": "../../node_modules/turbo/schema.json",
-  "extends": ["//"],
-  "tasks": {
-    "build": {
-      "outputs": ["out/**"]
-    },
-    "dist": {
-      "dependsOn": ["build", "@furtherverse/server#compile"],
-      "outputs": ["dist/**"]
-    },
-    "dist:linux": {
-      "dependsOn": ["build", "@furtherverse/server#compile:linux:arm64", "@furtherverse/server#compile:linux:x64"],
-      "outputs": ["dist/**"]
-    },
-    "dist:linux:arm64": {
-      "dependsOn": ["build", "@furtherverse/server#compile:linux:arm64"],
-      "outputs": ["dist/**"]
-    },
-    "dist:linux:x64": {
-      "dependsOn": ["build", "@furtherverse/server#compile:linux:x64"],
-      "outputs": ["dist/**"]
-    },
-    "dist:mac": {
-      "dependsOn": ["build", "@furtherverse/server#compile:darwin:arm64", "@furtherverse/server#compile:darwin:x64"],
-      "outputs": ["dist/**"]
-    },
-    "dist:mac:arm64": {
-      "dependsOn": ["build", "@furtherverse/server#compile:darwin:arm64"],
-      "outputs": ["dist/**"]
-    },
-    "dist:mac:x64": {
-      "dependsOn": ["build", "@furtherverse/server#compile:darwin:x64"],
-      "outputs": ["dist/**"]
-    },
-    "dist:win": {
-      "dependsOn": ["build", "@furtherverse/server#compile:windows:x64"],
-      "outputs": ["dist/**"]
-    }
-  }
-}

apps/server/.env.example

@@ -1 +0,0 @@
-DATABASE_URL=postgres://postgres:postgres@localhost:5432/postgres

apps/server/AGENTS.md

@@ -1,279 +0,0 @@
-# AGENTS.md - Server App Guidelines
-
-TanStack Start fullstack web app with ORPC (contract-first RPC).
-
-## Tech Stack
-
-> **⚠️ This project uses Bun — NOT Node.js / npm. All commands use `bun`. Always use `bun run <script>` (not `bun <script>`) to avoid conflicts with Bun built-in subcommands. Never use `npm`, `npx`, or `node`.**
-
-- **Framework**: TanStack Start (React 19 SSR, file-based routing)
-- **Runtime**: Bun — **NOT Node.js**
-- **Package Manager**: Bun — **NOT npm / yarn / pnpm**
-- **Language**: TypeScript (strict mode)
-- **Styling**: Tailwind CSS v4
-- **Database**: PostgreSQL + Drizzle ORM v1 beta (`drizzle-orm/postgres-js`, RQBv2)
-- **State**: TanStack Query v5
-- **RPC**: ORPC (contract-first, type-safe)
-- **Build**: Vite + Nitro
-
-## Commands
-
-```bash
-# Development
-bun run dev                    # Vite dev server (localhost:3000)
-bun run db:studio              # Drizzle Studio GUI
-
-# Build
-bun run build                  # Production build → .output/
-bun run compile                # Compile to standalone binary (current platform, depends on build)
-bun run compile:darwin         # Compile for macOS (arm64 + x64)
-bun run compile:darwin:arm64   # Compile for macOS arm64
-bun run compile:darwin:x64     # Compile for macOS x64
-bun run compile:linux          # Compile for Linux (x64 + arm64)
-bun run compile:linux:arm64    # Compile for Linux arm64
-bun run compile:linux:x64      # Compile for Linux x64
-bun run compile:windows        # Compile for Windows (default: x64)
-bun run compile:windows:x64    # Compile for Windows x64
-
-# Code Quality
-bun run fix                    # Biome auto-fix
-bun run typecheck              # TypeScript check
-
-# Database
-bun run db:generate            # Generate migrations from schema
-bun run db:migrate             # Run migrations
-bun run db:push                # Push schema directly (dev only)
-
-# Testing (not yet configured)
-bun test path/to/test.ts       # Run single test
-bun test -t "pattern"          # Run tests matching pattern
-```
-
-## Directory Structure
-
-```
-src/
-├── client/                # Client-side code
-│   └── orpc.ts            # ORPC client + TanStack Query utils (single entry point)
-├── components/            # React components
-├── routes/                # TanStack Router file routes
-│   ├── __root.tsx         # Root layout
-│   ├── index.tsx          # Home page
-│   └── api/
-│       ├── $.ts           # OpenAPI handler + Scalar docs
-│       ├── health.ts      # Health check endpoint
-│       └── rpc.$.ts       # ORPC RPC handler
-├── server/                # Server-side code
-│   ├── api/               # ORPC layer
-│   │   ├── contracts/     # Input/output schemas (Zod)
-│   │   ├── middlewares/   # Middleware (db provider, auth)
-│   │   ├── routers/       # Handler implementations
-│   │   ├── interceptors.ts # Shared error interceptors
-│   │   ├── context.ts     # Request context
-│   │   ├── server.ts      # ORPC server instance
-│   │   └── types.ts       # Type exports
-│   └── db/
-│       ├── schema/        # Drizzle table definitions
-│       ├── fields.ts      # Shared field builders (id, createdAt, updatedAt)
-│       ├── relations.ts   # Drizzle relations (defineRelations, RQBv2)
-│       └── index.ts       # Database instance (postgres-js driver)
-├── env.ts                 # Environment variable validation
-├── router.tsx             # Router configuration
-├── routeTree.gen.ts       # Auto-generated (DO NOT EDIT)
-└── styles.css             # Tailwind entry
-```
-
-## ORPC Pattern
-
-### 1. Define Contract (`src/server/api/contracts/feature.contract.ts`)
-```typescript
-import { oc } from '@orpc/contract'
-import { createSelectSchema } from 'drizzle-orm/zod'
-import { z } from 'zod'
-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)
-```
-
-### 2. Implement Router (`src/server/api/routers/feature.router.ts`)
-```typescript
-import { ORPCError } from '@orpc/server'
-import { db } from '../middlewares'
-import { os } from '../server'
-
-export const list = os.feature.list.use(db).handler(async ({ context }) => {
-  return await context.db.query.featureTable.findMany({
-    orderBy: { createdAt: 'desc' },
-  })
-})
-```
-
-### 3. Register in Index Files
-```typescript
-// src/server/api/contracts/index.ts
-import * as feature from './feature.contract'
-export const contract = { feature }
-
-// src/server/api/routers/index.ts
-import * as feature from './feature.router'
-export const router = os.router({ feature })
-```
-
-### 4. Use in Components
-```typescript
-import { useSuspenseQuery, useMutation } from '@tanstack/react-query'
-import { orpc } from '@/client/orpc'
-
-const { data } = useSuspenseQuery(orpc.feature.list.queryOptions())
-const mutation = useMutation(orpc.feature.create.mutationOptions())
-```
-
-## Database (Drizzle ORM v1 beta)
-
-- **Driver**: `drizzle-orm/postgres-js` (NOT `bun-sql`)
-- **Validation**: `drizzle-orm/zod` (built-in, NOT separate `drizzle-zod` package)
-- **Relations**: Defined via `defineRelations()` in `src/server/db/relations.ts`
-- **Query**: RQBv2 — use `db.query.tableName.findMany()` with object-style `orderBy` and `where`
-
-### Schema Definition
-```typescript
-import { pgTable, text, timestamp, uuid } from 'drizzle-orm/pg-core'
-import { sql } from 'drizzle-orm'
-
-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()),
-})
-```
-
-### Relations (RQBv2)
-```typescript
-// src/server/db/relations.ts
-import { defineRelations } from 'drizzle-orm'
-import * as schema from './schema'
-
-export const relations = defineRelations(schema, (r) => ({
-  // Define relations here using r.one / r.many / r.through
-}))
-```
-
-### DB Instance
-```typescript
-// src/server/db/index.ts
-import { drizzle } from 'drizzle-orm/postgres-js'
-import { relations } from '@/server/db/relations'
-// In RQBv2, relations already contain schema info — no separate schema import needed
-
-const db = drizzle({
-  connection: env.DATABASE_URL,
-  relations,
-})
-```
-
-### RQBv2 Query Examples
-```typescript
-// Object-style orderBy (NOT callback style)
-const todos = await db.query.todoTable.findMany({
-  orderBy: { createdAt: 'desc' },
-})
-
-// Object-style where
-const todo = await db.query.todoTable.findFirst({
-  where: { id: someId },
-})
-```
-
-## Code Style
-
-### 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 { ... }`)
-
-```typescript
-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 env = createEnv({
-  server: {
-    DATABASE_URL: z.string().url(),
-  },
-  clientPrefix: 'VITE_',
-  client: {
-    VITE_API_URL: z.string().optional(),
-  },
-})
-```
-
-## Development Principles
-
-> **These principles apply to ALL code changes. Agents MUST follow them on every task.**
-
-1. **No backward compatibility** — This project is in rapid iteration. Always use the latest API and patterns. Never keep deprecated code paths or old API fallbacks.
-2. **Always sync documentation** — When code changes, immediately update all related documentation (`AGENTS.md`, `README.md`, inline code examples). Code and docs must never drift apart.
-3. **Forward-only migration** — When upgrading dependencies, fully adopt the new API. Don't mix old and new patterns.
-
-## Critical Rules
-
-**DO:**
-- Run `bun run fix` before committing
-- Use `@/*` path aliases
-- Include `createdAt`/`updatedAt` on all tables
-- Use `ORPCError` with proper codes
-- Use `drizzle-orm/zod` (NOT `drizzle-zod`) for schema validation
-- Use RQBv2 object syntax for `orderBy` and `where`
-- Update `AGENTS.md` and other docs whenever code patterns change
-
-**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
-- Import from `drizzle-zod` (use `drizzle-orm/zod` instead)
-- Use RQBv1 callback-style `orderBy` / old `relations()` API
-- Use `drizzle-orm/bun-sql` driver (use `drizzle-orm/postgres-js`)
-- Pass `schema` to `drizzle()` constructor (only `relations` is needed in RQBv2)
-- Import `os` from `@orpc/server` in middleware — use `@/server/api/server` (the local typed instance)
-- Leave docs out of sync with code changes

apps/server/biome.json

@@ -1,12 +0,0 @@
-{
-  "$schema": "../../node_modules/@biomejs/biome/configuration_schema.json",
-  "extends": "//",
-  "files": {
-    "includes": ["**", "!**/routeTree.gen.ts"]
-  },
-  "css": {
-    "parser": {
-      "tailwindDirectives": true
-    }
-  }
-}

apps/server/package.json

@@ -1,60 +0,0 @@
-{
-  "name": "@furtherverse/server",
-  "version": "1.0.0",
-  "private": true,
-  "type": "module",
-  "scripts": {
-    "build": "bunx --bun vite build",
-    "compile": "bun compile.ts",
-    "compile:darwin": "bun run compile:darwin:arm64 && bun run compile:darwin:x64",
-    "compile:darwin:arm64": "bun compile.ts --target bun-darwin-arm64",
-    "compile:darwin:x64": "bun compile.ts --target bun-darwin-x64",
-    "compile:linux": "bun run compile:linux:x64 && bun run compile:linux:arm64",
-    "compile:linux:arm64": "bun compile.ts --target bun-linux-arm64",
-    "compile:linux:x64": "bun compile.ts --target bun-linux-x64",
-    "compile:windows": "bun run compile:windows:x64",
-    "compile:windows:x64": "bun compile.ts --target bun-windows-x64",
-    "db:generate": "drizzle-kit generate",
-    "db:migrate": "drizzle-kit migrate",
-    "db:push": "drizzle-kit push",
-    "db:studio": "drizzle-kit studio",
-    "dev": "bunx --bun vite dev",
-    "fix": "biome check --write",
-    "typecheck": "tsc --noEmit"
-  },
-  "dependencies": {
-    "@orpc/client": "catalog:",
-    "@orpc/contract": "catalog:",
-    "@orpc/openapi": "catalog:",
-    "@orpc/server": "catalog:",
-    "@orpc/tanstack-query": "catalog:",
-    "@orpc/zod": "catalog:",
-    "@t3-oss/env-core": "catalog:",
-    "@tanstack/react-query": "catalog:",
-    "@tanstack/react-router": "catalog:",
-    "@tanstack/react-router-ssr-query": "catalog:",
-    "@tanstack/react-start": "catalog:",
-    "drizzle-orm": "catalog:",
-    "postgres": "catalog:",
-    "react": "catalog:",
-    "react-dom": "catalog:",
-    "uuid": "catalog:",
-    "zod": "catalog:"
-  },
-  "devDependencies": {
-    "@furtherverse/tsconfig": "workspace:*",
-    "@tailwindcss/vite": "catalog:",
-    "@tanstack/devtools-vite": "catalog:",
-    "@tanstack/react-devtools": "catalog:",
-    "@tanstack/react-query-devtools": "catalog:",
-    "@tanstack/react-router-devtools": "catalog:",
-    "@types/bun": "catalog:",
-    "@vitejs/plugin-react": "catalog:",
-    "babel-plugin-react-compiler": "catalog:",
-    "drizzle-kit": "catalog:",
-    "nitro": "catalog:",
-    "tailwindcss": "catalog:",
-    "vite": "catalog:",
-    "vite-tsconfig-paths": "catalog:"
-  }
-}

apps/server/public/robots.txt

@@ -1,3 +0,0 @@
-# https://www.robotstxt.org/robotstxt.html
-User-agent: *
-Disallow:

apps/server/src/components/Error.tsx

@@ -1,3 +0,0 @@
-export function ErrorComponent() {
-  return <div>An unhandled error happened!</div>
-}

apps/server/src/components/NotFound.tsx

@@ -1,3 +0,0 @@
-export function NotFoundComponent() {
-  return <div>404 - Not Found</div>
-}

apps/server/src/env.ts

@@ -1,14 +0,0 @@
-import { createEnv } from '@t3-oss/env-core'
-import { z } from 'zod'
-
-export const env = createEnv({
-  server: {
-    DATABASE_URL: z.url(),
-  },
-  clientPrefix: 'VITE_',
-  client: {
-    VITE_APP_TITLE: z.string().min(1).optional(),
-  },
-  runtimeEnv: process.env,
-  emptyStringAsUndefined: true,
-})

apps/server/src/routes/api/health.ts

@@ -1,27 +0,0 @@
-import { createFileRoute } from '@tanstack/react-router'
-import { name, version } from '@/../package.json'
-
-const createHealthResponse = (): Response =>
-  Response.json(
-    {
-      status: 'ok',
-      service: name,
-      version,
-      timestamp: new Date().toISOString(),
-    },
-    {
-      status: 200,
-      headers: {
-        'cache-control': 'no-store',
-      },
-    },
-  )
-
-export const Route = createFileRoute('/api/health')({
-  server: {
-    handlers: {
-      GET: async () => createHealthResponse(),
-      HEAD: async () => new Response(null, { status: 200 }),
-    },
-  },
-})

apps/server/src/routes/index.tsx

@@ -1,193 +0,0 @@
-import { useMutation, useSuspenseQuery } from '@tanstack/react-query'
-import { createFileRoute } from '@tanstack/react-router'
-import type { ChangeEventHandler, SubmitEventHandler } from 'react'
-import { useState } from 'react'
-import { orpc } from '@/client/orpc'
-
-export const Route = createFileRoute('/')({
-  component: Todos,
-  loader: async ({ context }) => {
-    await context.queryClient.ensureQueryData(orpc.todo.list.queryOptions())
-  },
-})
-
-function Todos() {
-  const [newTodoTitle, setNewTodoTitle] = useState('')
-
-  const listQuery = useSuspenseQuery(orpc.todo.list.queryOptions())
-  const createMutation = useMutation(orpc.todo.create.mutationOptions())
-  const updateMutation = useMutation(orpc.todo.update.mutationOptions())
-  const deleteMutation = useMutation(orpc.todo.remove.mutationOptions())
-
-  const handleCreateTodo: SubmitEventHandler<HTMLFormElement> = (e) => {
-    e.preventDefault()
-    if (newTodoTitle.trim()) {
-      createMutation.mutate({ title: newTodoTitle.trim() })
-      setNewTodoTitle('')
-    }
-  }
-
-  const handleInputChange: ChangeEventHandler<HTMLInputElement> = (e) => {
-    setNewTodoTitle(e.target.value)
-  }
-
-  const handleToggleTodo = (id: string, currentCompleted: boolean) => {
-    updateMutation.mutate({
-      id,
-      data: { completed: !currentCompleted },
-    })
-  }
-
-  const handleDeleteTodo = (id: string) => {
-    deleteMutation.mutate({ id })
-  }
-
-  const todos = listQuery.data
-  const completedCount = todos.filter((todo) => todo.completed).length
-  const totalCount = todos.length
-  const progress = totalCount > 0 ? (completedCount / totalCount) * 100 : 0
-
-  return (
-    <div className="min-h-screen bg-slate-50 py-12 px-4 sm:px-6 font-sans">
-      <div className="max-w-2xl mx-auto space-y-8">
-        {/* Header */}
-        <div className="flex items-end justify-between">
-          <div>
-            <h1 className="text-3xl font-bold text-slate-900 tracking-tight">我的待办</h1>
-            <p className="text-slate-500 mt-1">保持专注，逐个击破</p>
-          </div>
-          <div className="text-right">
-            <div className="text-2xl font-semibold text-slate-900">
-              {completedCount}
-              <span className="text-slate-400 text-lg">/{totalCount}</span>
-            </div>
-            <div className="text-xs font-medium text-slate-400 uppercase tracking-wider">已完成</div>
-          </div>
-        </div>
-
-        {/* Add Todo Form */}
-        <form onSubmit={handleCreateTodo} className="relative group z-10">
-          <div className="relative transform transition-all duration-200 focus-within:-translate-y-1">
-            <input
-              type="text"
-              value={newTodoTitle}
-              onChange={handleInputChange}
-              placeholder="添加新任务..."
-              className="w-full pl-6 pr-32 py-5 bg-white rounded-2xl shadow-[0_8px_30px_rgb(0,0,0,0.04)] border-0 ring-1 ring-slate-100 focus:ring-2 focus:ring-indigo-500/50 outline-none transition-all placeholder:text-slate-400 text-lg text-slate-700"
-              disabled={createMutation.isPending}
-            />
-            <button
-              type="submit"
-              disabled={createMutation.isPending || !newTodoTitle.trim()}
-              className="absolute right-3 top-3 bottom-3 px-6 bg-indigo-600 hover:bg-indigo-700 text-white rounded-xl font-medium transition-all shadow-md shadow-indigo-200 disabled:opacity-50 disabled:shadow-none hover:shadow-lg hover:shadow-indigo-300 active:scale-95"
-            >
-              {createMutation.isPending ? '添加中' : '添加'}
-            </button>
-          </div>
-        </form>
-
-        {/* Progress Bar (Only visible when there are tasks) */}
-        {totalCount > 0 && (
-          <div className="h-1.5 w-full bg-slate-200 rounded-full overflow-hidden">
-            <div
-              className="h-full bg-indigo-500 transition-all duration-500 ease-out rounded-full"
-              style={{ width: `${progress}%` }}
-            />
-          </div>
-        )}
-
-        {/* Todo List */}
-        <div className="space-y-3">
-          {todos.length === 0 ? (
-            <div className="py-20 text-center">
-              <div className="inline-flex items-center justify-center w-16 h-16 rounded-full bg-slate-100 mb-4">
-                <svg
-                  className="w-8 h-8 text-slate-400"
-                  fill="none"
-                  viewBox="0 0 24 24"
-                  stroke="currentColor"
-                  aria-hidden="true"
-                >
-                  <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M12 6v6m0 0v6m0-6h6m-6 0H6" />
-                </svg>
-              </div>
-              <p className="text-slate-500 text-lg font-medium">没有待办事项</p>
-              <p className="text-slate-400 text-sm mt-1">输入上方内容添加您的第一个任务</p>
-            </div>
-          ) : (
-            todos.map((todo) => (
-              <div
-                key={todo.id}
-                className={`group relative flex items-center p-4 bg-white rounded-xl border border-slate-100 shadow-sm transition-all duration-200 hover:shadow-md hover:border-slate-200 ${
-                  todo.completed ? 'bg-slate-50/50' : ''
-                }`}
-              >
-                <button
-                  type="button"
-                  onClick={() => handleToggleTodo(todo.id, todo.completed)}
-                  className={`flex-shrink-0 w-6 h-6 rounded-full border-2 transition-all duration-200 flex items-center justify-center mr-4 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-indigo-500 ${
-                    todo.completed
-                      ? 'bg-indigo-500 border-indigo-500'
-                      : 'border-slate-300 hover:border-indigo-500 bg-white'
-                  }`}
-                >
-                  {todo.completed && (
-                    <svg
-                      className="w-3.5 h-3.5 text-white"
-                      fill="none"
-                      viewBox="0 0 24 24"
-                      stroke="currentColor"
-                      strokeWidth={3}
-                      aria-hidden="true"
-                    >
-                      <path strokeLinecap="round" strokeLinejoin="round" d="M5 13l4 4L19 7" />
-                    </svg>
-                  )}
-                </button>
-
-                <div className="flex-1 min-w-0">
-                  <p
-                    className={`text-lg transition-all duration-200 truncate ${
-                      todo.completed
-                        ? 'text-slate-400 line-through decoration-slate-300 decoration-2'
-                        : 'text-slate-700'
-                    }`}
-                  >
-                    {todo.title}
-                  </p>
-                </div>
-
-                <div className="flex items-center opacity-0 group-hover:opacity-100 transition-opacity duration-200 absolute right-4 pl-4 bg-gradient-to-l from-white via-white to-transparent sm:static sm:bg-none">
-                  <span className="text-xs text-slate-400 mr-3 hidden sm:inline-block">
-                    {new Date(todo.createdAt).toLocaleDateString('zh-CN')}
-                  </span>
-                  <button
-                    type="button"
-                    onClick={() => handleDeleteTodo(todo.id)}
-                    className="p-2 text-slate-400 hover:text-red-500 hover:bg-red-50 rounded-lg transition-colors focus:outline-none"
-                    title="删除"
-                  >
-                    <svg
-                      className="w-5 h-5"
-                      fill="none"
-                      viewBox="0 0 24 24"
-                      stroke="currentColor"
-                      strokeWidth={1.5}
-                      aria-hidden="true"
-                    >
-                      <path
-                        strokeLinecap="round"
-                        strokeLinejoin="round"
-                        d="M19 7l-.867 12.142A2 2 0 0116.138 21H7.862a2 2 0 01-1.995-1.858L5 7m5 4v6m4-6v6m1-10V4a1 1 0 00-1-1h-4a1 1 0 00-1 1v3M4 7h16"
-                      />
-                    </svg>
-                  </button>
-                </div>
-              </div>
-            ))
-          )}
-        </div>
-      </div>
-    </div>
-  )
-}

apps/server/src/server/api/context.ts

@@ -1,25 +0,0 @@
-import type { DB } from '@/server/db'
-
-/**
- * 基础 Context - 所有请求都包含的上下文
- */
-export interface BaseContext {
-  headers: Headers
-}
-
-/**
- * 数据库 Context - 通过 db middleware 扩展
- */
-export interface DBContext extends BaseContext {
-  db: DB
-}
-
-/**
- * 认证 Context - 通过 auth middleware 扩展（未来使用）
- *
- * @example
- * export interface AuthContext extends DBContext {
- *   userId: string
- *   user: User
- * }
- */

apps/server/src/server/api/middlewares/db.middleware.ts

@@ -1,11 +0,0 @@
-import { os } from '@/server/api/server'
-import { getDB } from '@/server/db'
-
-export const db = os.middleware(async ({ context, next }) => {
-  return next({
-    context: {
-      ...context,
-      db: getDB(),
-    },
-  })
-})

apps/server/src/server/api/middlewares/index.ts

@@ -1 +0,0 @@
-export * from './db.middleware'

apps/server/src/server/api/routers/todo.router.ts

@@ -1,40 +0,0 @@
-import { ORPCError } from '@orpc/server'
-import { eq } from 'drizzle-orm'
-import { todoTable } from '@/server/db/schema'
-import { db } from '../middlewares'
-import { os } from '../server'
-
-export const list = os.todo.list.use(db).handler(async ({ context }) => {
-  const todos = await context.db.query.todoTable.findMany({
-    orderBy: { createdAt: 'desc' },
-  })
-  return todos
-})
-
-export const create = os.todo.create.use(db).handler(async ({ context, input }) => {
-  const [newTodo] = await context.db.insert(todoTable).values(input).returning()
-
-  if (!newTodo) {
-    throw new ORPCError('INTERNAL_SERVER_ERROR', { message: 'Failed to create todo' })
-  }
-
-  return newTodo
-})
-
-export const update = os.todo.update.use(db).handler(async ({ context, input }) => {
-  const [updatedTodo] = await context.db.update(todoTable).set(input.data).where(eq(todoTable.id, input.id)).returning()
-
-  if (!updatedTodo) {
-    throw new ORPCError('NOT_FOUND')
-  }
-
-  return updatedTodo
-})
-
-export const remove = os.todo.remove.use(db).handler(async ({ context, input }) => {
-  const [deleted] = await context.db.delete(todoTable).where(eq(todoTable.id, input.id)).returning({ id: todoTable.id })
-
-  if (!deleted) {
-    throw new ORPCError('NOT_FOUND')
-  }
-})

apps/server/src/server/api/types.ts

@@ -1,6 +0,0 @@
-import type { ContractRouterClient, InferContractRouterInputs, InferContractRouterOutputs } from '@orpc/contract'
-import type { Contract } from './contracts'
-
-export type RouterClient = ContractRouterClient<Contract>
-export type RouterInputs = InferContractRouterInputs<Contract>
-export type RouterOutputs = InferContractRouterOutputs<Contract>

apps/server/src/server/db/fields.ts

@@ -1,55 +0,0 @@
-import { sql } from 'drizzle-orm'
-import { timestamp, uuid } from 'drizzle-orm/pg-core'
-import { v7 as uuidv7 } from 'uuid'
-
-// id
-
-const id = (name: string) => uuid(name)
-export const pk = (name: string, strategy?: 'native' | 'extension') => {
-  switch (strategy) {
-    // PG 18+
-    case 'native':
-      return id(name).primaryKey().default(sql`uuidv7()`)
-
-    // PG 13+ with extension
-    case 'extension':
-      return id(name).primaryKey().default(sql`uuid_generate_v7()`)
-
-    // Any PG version
-    default:
-      return id(name)
-        .primaryKey()
-        .$defaultFn(() => uuidv7())
-  }
-}
-
-// timestamp
-
-export const createdAt = (name = 'created_at') => timestamp(name, { withTimezone: true }).notNull().defaultNow()
-
-export const updatedAt = (name = 'updated_at') =>
-  timestamp(name, { withTimezone: true })
-    .notNull()
-    .defaultNow()
-    .$onUpdateFn(() => new Date())
-
-// generated fields
-
-export const generatedFields = {
-  id: pk('id'),
-  createdAt: createdAt('created_at'),
-  updatedAt: updatedAt('updated_at'),
-}
-
-// Helper to create omit keys from generatedFields
-const createGeneratedFieldKeys = <T extends Record<string, unknown>>(fields: T): Record<keyof T, true> => {
-  return Object.keys(fields).reduce(
-    (acc, key) => {
-      acc[key as keyof T] = true
-      return acc
-    },
-    {} as Record<keyof T, true>,
-  )
-}
-
-export const generatedFieldKeys = createGeneratedFieldKeys(generatedFields)

apps/server/src/server/db/index.ts

@@ -1,24 +0,0 @@
-import { drizzle } from 'drizzle-orm/postgres-js'
-import { env } from '@/env'
-import { relations } from '@/server/db/relations'
-
-export const createDB = () =>
-  drizzle({
-    connection: env.DATABASE_URL,
-    relations,
-  })
-
-export type DB = ReturnType<typeof createDB>
-
-export const getDB = (() => {
-  let db: DB | null = null
-
-  return (singleton = true): DB => {
-    if (!singleton) {
-      return createDB()
-    }
-
-    db ??= createDB()
-    return db
-  }
-})()

apps/server/src/server/db/relations.ts

@@ -1,4 +0,0 @@
-import { defineRelations } from 'drizzle-orm'
-import * as schema from './schema'
-
-export const relations = defineRelations(schema, (_r) => ({}))

apps/server/src/styles.css

@@ -1 +0,0 @@
-@import "tailwindcss";

apps/server/tsconfig.json

@@ -1,9 +0,0 @@
-{
-  "extends": "@furtherverse/tsconfig/react.json",
-  "compilerOptions": {
-    "baseUrl": ".",
-    "paths": {
-      "@/*": ["./src/*"]
-    }
-  }
-}

apps/server/turbo.json

@@ -1,47 +0,0 @@
-{
-  "$schema": "../../node_modules/turbo/schema.json",
-  "extends": ["//"],
-  "tasks": {
-    "build": {
-      "env": ["NODE_ENV", "VITE_*"],
-      "inputs": ["src/**", "public/**", "package.json", "tsconfig.json", "vite.config.ts"],
-      "outputs": [".output/**"]
-    },
-    "compile": {
-      "dependsOn": ["build"],
-      "outputs": ["out/**"]
-    },
-    "compile:darwin": {
-      "dependsOn": ["build"],
-      "outputs": ["out/**"]
-    },
-    "compile:darwin:arm64": {
-      "dependsOn": ["build"],
-      "outputs": ["out/**"]
-    },
-    "compile:darwin:x64": {
-      "dependsOn": ["build"],
-      "outputs": ["out/**"]
-    },
-    "compile:linux": {
-      "dependsOn": ["build"],
-      "outputs": ["out/**"]
-    },
-    "compile:linux:arm64": {
-      "dependsOn": ["build"],
-      "outputs": ["out/**"]
-    },
-    "compile:linux:x64": {
-      "dependsOn": ["build"],
-      "outputs": ["out/**"]
-    },
-    "compile:windows": {
-      "dependsOn": ["build"],
-      "outputs": ["out/**"]
-    },
-    "compile:windows:x64": {
-      "dependsOn": ["build"],
-      "outputs": ["out/**"]
-    }
-  }
-}

biome.json

@@ -6,7 +6,8 @@
     "useIgnoreFile": true
   },
   "files": {
-    "ignoreUnknown": false
+    "ignoreUnknown": false,
+    "includes": ["**", "!**/routeTree.gen.ts", "!**/migrations.gen.ts"]
   },
   "formatter": {
     "enabled": true,
@@ -16,6 +17,11 @@
   },
   "linter": {
     "enabled": true,
+    "domains": {
+      "drizzle": "recommended",
+      "react": "recommended",
+      "types": "all"
+    },
     "rules": {
       "recommended": true,
       "complexity": {
@@ -23,6 +29,14 @@
       },
       "correctness": {
         "noReactPropAssignments": "error"
+      },
+      "style": {
+        "noNonNullAssertion": "error"
+      },
+      "suspicious": {
+        "noExplicitAny": "error",
+        "noImportCycles": "error",
+        "noTsIgnore": "error"
       }
     }
   },
@@ -33,6 +47,11 @@
       "arrowParentheses": "always"
     }
   },
+  "css": {
+    "parser": {
+      "tailwindDirectives": true
+    }
+  },
   "assist": {
     "enabled": true,
     "actions": {

bunfig.toml

@@ -1,2 +0,0 @@
-[install]
-publicHoistPattern = ["@types/*", "bun-types", "nitro*"]

compose.yaml

@@ -0,0 +1,39 @@
+services:
+  migrate:
+    build: .
+    depends_on:
+      db:
+        condition: service_healthy
+    environment:
+      - DATABASE_URL=postgres://postgres:postgres@db:5432/postgres
+    command: ["./server", "migrate"]
+    restart: "no"
+
+  app:
+    build: .
+    depends_on:
+      db:
+        condition: service_healthy
+      migrate:
+        condition: service_completed_successfully
+    ports:
+      - "3000:3000"
+    environment:
+      - DATABASE_URL=postgres://postgres:postgres@db:5432/postgres
+
+  db:
+    image: postgres:18-alpine
+    volumes:
+      - postgres_data:/var/lib/postgresql
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: postgres
+    healthcheck:
+      test: [ "CMD", "pg_isready", "-U", "postgres" ]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+volumes:
+  postgres_data:

drizzle.config.ts

@@ -1,5 +1,5 @@
 import { defineConfig } from 'drizzle-kit'
-import { env } from '@/env'
+import { env } from './src/env'
 
 export default defineConfig({
   out: './drizzle',

drizzle/0000_loving_thunderbird.sql

@@ -0,0 +1,7 @@
+CREATE TABLE "todo" (
+	"id" uuid PRIMARY KEY NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"title" text NOT NULL,
+	"completed" boolean DEFAULT false NOT NULL
+);

drizzle/meta/0000_snapshot.json

@@ -0,0 +1,65 @@
+{
+  "id": "4ece5479-57bf-473d-b806-c1176c972e7f",
+  "prevId": "00000000-0000-0000-0000-000000000000",
+  "version": "7",
+  "dialect": "postgresql",
+  "tables": {
+    "public.todo": {
+      "name": "todo",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "title": {
+          "name": "title",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "completed": {
+          "name": "completed",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    }
+  },
+  "enums": {},
+  "schemas": {},
+  "sequences": {},
+  "roles": {},
+  "policies": {},
+  "views": {},
+  "_meta": {
+    "columns": {},
+    "schemas": {},
+    "tables": {}
+  }
+}

drizzle/meta/_journal.json

@@ -0,0 +1,13 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1777096386609,
+      "tag": "0000_loving_thunderbird",
+      "breakpoints": true
+    }
+  ]
+}

mise.toml

@@ -1,3 +1,2 @@
 [tools]
-bun = "1"
+bun = "1.3.13"
-node = "24"

opencode.jsonc

@@ -1,13 +0,0 @@
-{
-  "$schema": "https://opencode.ai/config.json",
-  "mcp": {
-    "shadcn": {
-      "type": "local",
-      "command": ["bunx", "--bun", "shadcn", "mcp"]
-    },
-    "tanstack": {
-      "type": "remote",
-      "url": "https://tanstack.com/api/mcp"
-    }
-  }
-}

package.json

@@ -1,70 +1,71 @@
 {
-  "name": "@furtherverse/monorepo",
+  "name": "fullstack-starter",
   "version": "1.0.0",
   "private": true,
   "type": "module",
-  "workspaces": [
+  "imports": {
-    "apps/*",
+    "#drizzle/*.sql": "./drizzle/*.sql",
-    "packages/*"
+    "#package": "./package.json",
-  ],
+    "#server": "./.output/server/index.mjs"
+  },
   "scripts": {
-    "build": "turbo run build",
+    "build": "bunx --bun vite build",
-    "compile": "turbo run compile",
+    "cli": "bun src/bin.ts",
-    "compile:darwin": "turbo run compile:darwin",
+    "compile": "bun scripts/compile.ts",
-    "compile:linux": "turbo run compile:linux",
+    "compile:darwin": "bun run compile:darwin:arm64 && bun run compile:darwin:x64",
-    "compile:windows": "turbo run compile:windows",
+    "compile:darwin:arm64": "bun scripts/compile.ts --target bun-darwin-arm64",
-    "dev": "turbo run dev",
+    "compile:darwin:x64": "bun scripts/compile.ts --target bun-darwin-x64",
-    "dist": "turbo run dist",
+    "compile:linux": "bun run compile:linux:x64 && bun run compile:linux:arm64",
-    "dist:linux": "turbo run dist:linux",
+    "compile:linux:arm64": "bun scripts/compile.ts --target bun-linux-arm64",
-    "dist:mac": "turbo run dist:mac",
+    "compile:linux:x64": "bun scripts/compile.ts --target bun-linux-x64",
-    "dist:win": "turbo run dist:win",
+    "compile:windows": "bun run compile:windows:x64",
-    "fix": "turbo run fix",
+    "compile:windows:x64": "bun scripts/compile.ts --target bun-windows-x64",
-    "typecheck": "turbo run typecheck"
+    "db:embed": "bun scripts/embed-migrations.ts",
+    "db:generate": "drizzle-kit generate && bun scripts/embed-migrations.ts",
+    "db:migrate": "drizzle-kit migrate",
+    "db:push": "drizzle-kit push",
+    "db:studio": "drizzle-kit studio",
+    "dev": "bunx --bun vite dev",
+    "fix": "biome check --write",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
   },
-  "devDependencies": {
+  "dependencies": {
-    "@biomejs/biome": "^2.4.5",
+    "@logtape/drizzle-orm": "^2.0.5",
-    "turbo": "^2.8.13",
+    "@logtape/logtape": "^2.0.5",
-    "typescript": "^5.9.3"
+    "@logtape/pretty": "^2.0.5",
-  },
+    "@orpc/client": "^1.14.0",
-  "catalog": {
+    "@orpc/contract": "^1.14.0",
-    "@orpc/client": "^1.13.6",
+    "@orpc/openapi": "^1.14.0",
-    "@orpc/contract": "^1.13.6",
+    "@orpc/server": "^1.14.0",
-    "@orpc/openapi": "^1.13.6",
+    "@orpc/tanstack-query": "^1.14.0",
-    "@orpc/server": "^1.13.6",
+    "@orpc/zod": "^1.14.0",
-    "@orpc/tanstack-query": "^1.13.6",
+    "@t3-oss/env-core": "^0.13.11",
-    "@orpc/zod": "^1.13.6",
+    "@tanstack/react-query": "^5.100.1",
-    "@t3-oss/env-core": "^0.13.10",
+    "@tanstack/react-router": "^1.168.24",
-    "@tailwindcss/vite": "^4.2.1",
+    "@tanstack/react-router-ssr-query": "^1.166.11",
-    "@tanstack/devtools-vite": "^0.5.3",
+    "@tanstack/react-start": "^1.167.48",
-    "@tanstack/react-devtools": "^0.9.9",
+    "citty": "^0.2.2",
-    "@tanstack/react-query": "^5.90.21",
+    "drizzle-orm": "0.45.2",
-    "@tanstack/react-query-devtools": "^5.91.3",
+    "drizzle-zod": "^0.8.3",
-    "@tanstack/react-router": "^1.166.2",
+    "postgres": "^3.4.9",
-    "@tanstack/react-router-devtools": "^1.166.2",
+    "react": "^19.2.5",
-    "@tanstack/react-router-ssr-query": "^1.166.2",
+    "react-dom": "^19.2.5",
-    "@tanstack/react-start": "^1.166.2",
-    "@types/bun": "^1.3.10",
-    "@types/node": "^24.11.0",
-    "@vitejs/plugin-react": "^5.1.4",
-    "babel-plugin-react-compiler": "^1.0.0",
-    "drizzle-kit": "1.0.0-beta.15-859cf75",
-    "drizzle-orm": "1.0.0-beta.15-859cf75",
-    "electron": "^34.0.0",
-    "electron-builder": "^26.8.1",
-    "electron-vite": "^5.0.0",
-    "motion": "^12.35.0",
-    "nitro": "npm:nitro-nightly@3.0.1-20260227-181935-bfbb207c",
-    "postgres": "^3.4.8",
-    "react": "^19.2.4",
-    "react-dom": "^19.2.4",
-    "tailwindcss": "^4.2.1",
-    "tree-kill": "^1.2.2",
-    "uuid": "^13.0.0",
-    "vite": "^8.0.0-beta.16",
-    "vite-tsconfig-paths": "^6.1.1",
     "zod": "^4.3.6"
   },
-  "overrides": {
+  "devDependencies": {
-    "@types/node": "catalog:"
+    "@biomejs/biome": "^2.4.13",
+    "@tailwindcss/vite": "^4.2.4",
+    "@tanstack/devtools-vite": "^0.6.0",
+    "@tanstack/react-devtools": "^0.10.2",
+    "@tanstack/react-query-devtools": "^5.100.1",
+    "@tanstack/react-router-devtools": "^1.166.13",
+    "@types/bun": "^1.3.13",
+    "@vitejs/plugin-react": "^6.0.1",
+    "drizzle-kit": "0.31.10",
+    "nitro": "npm:nitro-nightly@3.0.1-20260424-182106-f8cf6ccc",
+    "tailwindcss": "^4.2.4",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.10"
   }
 }

packages/tsconfig/bun.json

@@ -1,8 +0,0 @@
-{
-  "$schema": "https://json.schemastore.org/tsconfig",
-  "display": "Bun",
-  "extends": "./base.json",
-  "compilerOptions": {
-    "types": ["bun-types"]
-  }
-}

packages/tsconfig/package.json

@@ -1,11 +0,0 @@
-{
-  "name": "@furtherverse/tsconfig",
-  "version": "1.0.0",
-  "private": true,
-  "type": "module",
-  "exports": {
-    "./base.json": "./base.json",
-    "./bun.json": "./bun.json",
-    "./react.json": "./react.json"
-  }
-}

packages/tsconfig/react.json

@@ -1,9 +0,0 @@
-{
-  "$schema": "https://json.schemastore.org/tsconfig",
-  "display": "React",
-  "extends": "./base.json",
-  "compilerOptions": {
-    "lib": ["ESNext", "DOM", "DOM.Iterable"],
-    "jsx": "react-jsx"
-  }
-}

public/robots.txt

@@ -0,0 +1,2 @@
+User-agent: *
+Disallow:

scripts/compile.ts

@@ -1,7 +1,8 @@
 import { mkdir, rm } from 'node:fs/promises'
+import { basename } from 'node:path'
 import { parseArgs } from 'node:util'
 
-const ENTRYPOINT = '.output/server/index.mjs'
+const ENTRYPOINT = 'src/bin.ts'
 const OUTDIR = 'out'
 
 const SUPPORTED_TARGETS: readonly Bun.Build.CompileTarget[] = [
@@ -12,8 +13,9 @@ const SUPPORTED_TARGETS: readonly Bun.Build.CompileTarget[] = [
   'bun-linux-arm64',
 ]
 
-const isSupportedTarget = (value: string): value is Bun.Build.CompileTarget =>
+const SUPPORTED_TARGET_SET: ReadonlySet<string> = new Set(SUPPORTED_TARGETS)
-  (SUPPORTED_TARGETS as readonly string[]).includes(value)
+
+const isSupportedTarget = (value: string): value is Bun.Build.CompileTarget => SUPPORTED_TARGET_SET.has(value)
 
 const { values } = parseArgs({
   options: { target: { type: 'string' } },
@@ -48,13 +50,20 @@ const main = async () => {
   const result = await Bun.build({
     entrypoints: [ENTRYPOINT],
     outdir: OUTDIR,
-    compile: { outfile, target },
+    // autoloadDotenv: false — produce a deterministic binary; it must not silently consume a .env from cwd.
+    compile: { outfile, target, autoloadDotenv: false },
+    minify: true,
+    bytecode: true,
+    sourcemap: 'inline',
   })
 
   if (!result.success) {
     throw new Error(result.logs.map(String).join('\n'))
   }
 
+  // Bun bundler still writes *.js.map next to the binary even with inline sourcemap.
+  await rm(`${OUTDIR}/${basename(ENTRYPOINT, '.ts')}.js.map`, { force: true })
+
   console.log(`✓ ${target} → ${OUTDIR}/${outfile}`)
 }
 

scripts/embed-migrations.ts

@@ -0,0 +1,51 @@
+import { existsSync } from 'node:fs'
+import { readFile, writeFile } from 'node:fs/promises'
+import { z } from 'zod'
+
+const JOURNAL = './drizzle/meta/_journal.json'
+const OUTPUT = './src/server/db/migrations.gen.ts'
+
+const journalEntrySchema = z.object({
+  idx: z.number().int().nonnegative(),
+  tag: z.string().regex(/^\d{4}_[a-z0-9_]+$/),
+  when: z.number().int().nonnegative(),
+  breakpoints: z.boolean(),
+})
+const journalSchema = z.object({ entries: z.array(journalEntrySchema).default([]) })
+
+type JournalEntry = z.infer<typeof journalEntrySchema>
+
+const readJournalEntries = async (): Promise<JournalEntry[]> => {
+  if (!existsSync(JOURNAL)) {
+    return []
+  }
+  const raw: unknown = JSON.parse(await readFile(JOURNAL, 'utf-8'))
+  return journalSchema.parse(raw).entries.sort((a, b) => a.idx - b.idx)
+}
+
+const main = async () => {
+  const entries = await readJournalEntries()
+
+  const imports = entries
+    .map((e) => `import sql_${e.idx} from '#drizzle/${e.tag}.sql' with { type: 'text' }`)
+    .join('\n')
+
+  const arrayBody = entries.length
+    ? `[\n${entries.map((e) => `  { tag: '${e.tag}', sql: sql_${e.idx}, when: ${e.when}, breakpoints: ${e.breakpoints} },`).join('\n')}\n]`
+    : '[]'
+
+  const out = `// AUTO-GENERATED by \`bun run db:embed\`. Do not edit.
+${imports ? `${imports}\n` : ''}
+export type EmbeddedMigration = { tag: string; sql: string; when: number; breakpoints: boolean }
+
+export const embeddedMigrations: readonly EmbeddedMigration[] = ${arrayBody}
+`
+
+  await writeFile(OUTPUT, out)
+  console.log(`✓ ${OUTPUT} (${entries.length} migration${entries.length === 1 ? '' : 's'})`)
+}
+
+main().catch((err) => {
+  console.error('❌', err instanceof Error ? err.message : err)
+  process.exit(1)
+})

src/bin.ts

@@ -0,0 +1,21 @@
+import { defineCommand, runMain } from 'citty'
+import { name, version } from '#package'
+
+// IMPORTANT: keep this file's static imports minimal. Nitro's bun preset
+// emits `.output/server/index.mjs` with a top-level `serve(...)` call, so any
+// eager (transitive) import of it would start the HTTP server even for
+// `migrate` or `--help`. All subcommands are lazy-loaded via citty.
+const main = defineCommand({
+  meta: {
+    name,
+    version,
+    description: 'Fullstack server binary (default subcommand: serve)',
+  },
+  default: 'serve',
+  subCommands: {
+    serve: () => import('@/cli/serve').then((m) => m.default),
+    migrate: () => import('@/cli/migrate').then((m) => m.default),
+  },
+})
+
+runMain(main)

src/cli/_serve-nitro.d.mts

@@ -0,0 +1 @@
+export default function startNitroServer(): Promise<void>

src/cli/_serve-nitro.mjs

@@ -0,0 +1,3 @@
+export default async function startNitroServer() {
+  await import('#server')
+}

src/cli/migrate.ts

@@ -0,0 +1,84 @@
+import { defineCommand } from 'citty'
+
+export default defineCommand({
+  meta: {
+    name: 'migrate',
+    description: 'Apply pending database migrations',
+  },
+  async run() {
+    const [{ env }, { drizzle }, { sql }, { embeddedMigrations }, { getLogger }] = await Promise.all([
+      import('@/env'),
+      import('drizzle-orm/postgres-js'),
+      import('drizzle-orm'),
+      import('@/server/db/migrations.gen'),
+      import('@/server/logger'),
+    ])
+
+    const logger = getLogger(['cli', 'migrate'])
+
+    if (embeddedMigrations.length === 0) {
+      logger.info('No migrations bundled into this binary.')
+      return
+    }
+
+    const sha256 = (s: string) => Bun.CryptoHasher.hash('sha256', s, 'hex')
+
+    const db = drizzle({
+      connection: {
+        url: env.DATABASE_URL,
+        max: 1,
+        onnotice: (n) => logger.debug('pg notice', { notice: n.message }),
+      },
+    })
+    try {
+      await db.execute(sql`CREATE SCHEMA IF NOT EXISTS "drizzle"`)
+      await db.execute(sql`
+        CREATE TABLE IF NOT EXISTS "drizzle"."__drizzle_migrations" (
+          id SERIAL PRIMARY KEY,
+          hash text NOT NULL,
+          created_at bigint
+        )
+      `)
+
+      const applied = await db.execute<{ hash: string; created_at: string | null }>(
+        sql`SELECT hash, created_at FROM "drizzle"."__drizzle_migrations" ORDER BY created_at ASC`,
+      )
+
+      // Reject schema drift: any applied migration whose embedded SQL has changed (or is missing) is fatal.
+      for (const row of applied) {
+        const when = Number(row.created_at)
+        const m = embeddedMigrations.find((e) => e.when === when)
+        if (!m) {
+          throw new Error(`Applied migration when=${when} is not in this binary; do not roll back applied migrations.`)
+        }
+        if (sha256(m.sql) !== row.hash) {
+          throw new Error(`Migration hash mismatch at when=${when}; do not edit migrations after they are applied.`)
+        }
+      }
+
+      const appliedWhens = new Set(applied.map((r) => Number(r.created_at)))
+      const pending = embeddedMigrations.filter((m) => !appliedWhens.has(m.when))
+      if (pending.length === 0) {
+        logger.info('Database is up to date.')
+        return
+      }
+
+      logger.info('Applying {count} migration(s)...', { count: pending.length })
+      await db.transaction(async (tx) => {
+        for (const m of pending) {
+          for (const rawStmt of m.sql.split('--> statement-breakpoint')) {
+            const stmt = rawStmt.trim()
+            if (!stmt) continue
+            await tx.execute(sql.raw(stmt))
+          }
+          await tx.execute(
+            sql`INSERT INTO "drizzle"."__drizzle_migrations" ("hash", "created_at") VALUES (${sha256(m.sql)}, ${m.when})`,
+          )
+        }
+      })
+      logger.info('Migrations applied.')
+    } finally {
+      await db.$client.end()
+    }
+  },
+})

src/cli/serve.ts

@@ -0,0 +1,12 @@
+import { defineCommand } from 'citty'
+
+export default defineCommand({
+  meta: {
+    name: 'serve',
+    description: 'Start the HTTP server',
+  },
+  async run() {
+    const { default: startNitroServer } = await import('./_serve-nitro.mjs')
+    await startNitroServer()
+  },
+})

src/client/orpc.ts

@@ -24,30 +24,4 @@ const getORPCClient = createIsomorphicFn()
 
 const client: RouterClient = getORPCClient()
 
-export const orpc = createTanstackQueryUtils(client, {
+export const orpc = createTanstackQueryUtils(client)
-  experimental_defaults: {
-    todo: {
-      create: {
-        mutationOptions: {
-          onSuccess: (_, __, ___, ctx) => {
-            ctx.client.invalidateQueries({ queryKey: orpc.todo.list.key() })
-          },
-        },
-      },
-      update: {
-        mutationOptions: {
-          onSuccess: (_, __, ___, ctx) => {
-            ctx.client.invalidateQueries({ queryKey: orpc.todo.list.key() })
-          },
-        },
-      },
-      remove: {
-        mutationOptions: {
-          onSuccess: (_, __, ___, ctx) => {
-            ctx.client.invalidateQueries({ queryKey: orpc.todo.list.key() })
-          },
-        },
-      },
-    },
-  },
-})

src/client/queries/todo.ts

@@ -0,0 +1,7 @@
+import { useQueryClient } from '@tanstack/react-query'
+import { orpc } from '@/client/orpc'
+
+export const useInvalidateTodos = () => {
+  const queryClient = useQueryClient()
+  return () => queryClient.invalidateQueries({ queryKey: orpc.todo.list.key() })
+}

src/components/Error.tsx

@@ -0,0 +1,40 @@
+export const ErrorComponent = ({ error, reset }: { error: Error; reset: () => void }) => {
+  return (
+    <div className="min-h-screen flex items-center justify-center bg-slate-50 px-4">
+      <div className="max-w-md w-full text-center space-y-6">
+        <div className="inline-flex items-center justify-center w-16 h-16 rounded-full bg-red-100">
+          <svg
+            className="w-8 h-8 text-red-500"
+            fill="none"
+            viewBox="0 0 24 24"
+            stroke="currentColor"
+            strokeWidth={1.5}
+            aria-hidden="true"
+          >
+            <path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              d="M12 9v3.75m9-.75a9 9 0 11-18 0 9 9 0 0118 0zm-9 3.75h.008v.008H12v-.008z"
+            />
+          </svg>
+        </div>
+        <div>
+          <h1 className="text-2xl font-bold text-slate-900">出错了</h1>
+          <p className="text-slate-500 mt-2">{import.meta.env.DEV ? error.message : '请求失败，请稍后重试'}</p>
+        </div>
+        <div className="flex items-center justify-center gap-4">
+          <button
+            type="button"
+            onClick={reset}
+            className="px-6 py-2.5 bg-indigo-600 hover:bg-indigo-700 text-white rounded-xl font-medium transition-colors"
+          >
+            重试
+          </button>
+          <a href="/" className="px-6 py-2.5 text-slate-600 hover:text-slate-900 font-medium transition-colors">
+            返回首页
+          </a>
+        </div>
+      </div>
+    </div>
+  )
+}

src/components/NotFound.tsx

@@ -0,0 +1,23 @@
+import { Link } from '@tanstack/react-router'
+
+export const NotFoundComponent = () => {
+  return (
+    <div className="min-h-screen flex items-center justify-center bg-slate-50 px-4">
+      <div className="max-w-md w-full text-center space-y-6">
+        <div className="inline-flex items-center justify-center w-16 h-16 rounded-full bg-slate-100">
+          <span className="text-3xl font-bold text-slate-400">404</span>
+        </div>
+        <div>
+          <h1 className="text-2xl font-bold text-slate-900">页面不存在</h1>
+          <p className="text-slate-500 mt-2">您访问的页面可能已被移除或地址有误</p>
+        </div>
+        <Link
+          to="/"
+          className="inline-block px-6 py-2.5 bg-indigo-600 hover:bg-indigo-700 text-white rounded-xl font-medium transition-colors"
+        >
+          返回首页
+        </Link>
+      </div>
+    </div>
+  )
+}

src/components/TodoForm.tsx

@@ -0,0 +1,41 @@
+import type { SubmitEventHandler } from 'react'
+import { useState } from 'react'
+
+interface TodoFormProps {
+  onSubmit: (title: string) => void
+  isPending: boolean
+}
+
+export const TodoForm = ({ onSubmit, isPending }: TodoFormProps) => {
+  const [title, setTitle] = useState('')
+
+  const handleSubmit: SubmitEventHandler<HTMLFormElement> = (e) => {
+    e.preventDefault()
+    if (title.trim()) {
+      onSubmit(title.trim())
+      setTitle('')
+    }
+  }
+
+  return (
+    <form onSubmit={handleSubmit} className="relative group z-10">
+      <div className="relative transform transition-all duration-200 focus-within:-translate-y-1">
+        <input
+          type="text"
+          value={title}
+          onChange={(e) => setTitle(e.target.value)}
+          placeholder="添加新任务..."
+          className="w-full pl-6 pr-32 py-5 bg-white rounded-2xl shadow-[0_8px_30px_rgb(0,0,0,0.04)] border-0 ring-1 ring-slate-100 focus:ring-2 focus:ring-indigo-500/50 outline-none transition-all placeholder:text-slate-400 text-lg text-slate-700"
+          disabled={isPending}
+        />
+        <button
+          type="submit"
+          disabled={isPending || !title.trim()}
+          className="absolute right-3 top-3 bottom-3 px-6 bg-indigo-600 hover:bg-indigo-700 text-white rounded-xl font-medium transition-all shadow-md shadow-indigo-200 disabled:opacity-50 disabled:shadow-none hover:shadow-lg hover:shadow-indigo-300 active:scale-95"
+        >
+          {isPending ? '添加中' : '添加'}
+        </button>
+      </div>
+    </form>
+  )
+}

src/components/TodoItem.tsx

@@ -0,0 +1,77 @@
+import type { RouterOutputs } from '@/server/api/types'
+
+type Todo = RouterOutputs['todo']['list'][number]
+
+interface TodoItemProps {
+  todo: Todo
+  onToggle: (id: string, completed: boolean) => void
+  onDelete: (id: string) => void
+}
+
+export const TodoItem = ({ todo, onToggle, onDelete }: TodoItemProps) => {
+  return (
+    <div
+      className={`group relative flex items-center p-4 bg-white rounded-xl border border-slate-100 shadow-sm transition-all duration-200 hover:shadow-md hover:border-slate-200 ${
+        todo.completed ? 'bg-slate-50/50' : ''
+      }`}
+    >
+      <button
+        type="button"
+        onClick={() => onToggle(todo.id, todo.completed)}
+        className={`shrink-0 w-6 h-6 rounded-full border-2 transition-all duration-200 flex items-center justify-center mr-4 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-indigo-500 ${
+          todo.completed ? 'bg-indigo-500 border-indigo-500' : 'border-slate-300 hover:border-indigo-500 bg-white'
+        }`}
+      >
+        {todo.completed && (
+          <svg
+            className="w-3.5 h-3.5 text-white"
+            fill="none"
+            viewBox="0 0 24 24"
+            stroke="currentColor"
+            strokeWidth={3}
+            aria-hidden="true"
+          >
+            <path strokeLinecap="round" strokeLinejoin="round" d="M5 13l4 4L19 7" />
+          </svg>
+        )}
+      </button>
+
+      <div className="flex-1 min-w-0">
+        <p
+          className={`text-lg transition-all duration-200 truncate ${
+            todo.completed ? 'text-slate-400 line-through decoration-slate-300 decoration-2' : 'text-slate-700'
+          }`}
+        >
+          {todo.title}
+        </p>
+      </div>
+
+      <div className="flex items-center opacity-0 group-hover:opacity-100 transition-opacity duration-200 absolute right-4 pl-4 bg-linear-to-l from-white via-white to-transparent sm:static sm:bg-none">
+        <span className="text-xs text-slate-400 mr-3 hidden sm:inline-block">
+          {new Date(todo.createdAt).toLocaleDateString('zh-CN')}
+        </span>
+        <button
+          type="button"
+          onClick={() => onDelete(todo.id)}
+          className="p-2 text-slate-400 hover:text-red-500 hover:bg-red-50 rounded-lg transition-colors focus:outline-none"
+          title="删除"
+        >
+          <svg
+            className="w-5 h-5"
+            fill="none"
+            viewBox="0 0 24 24"
+            stroke="currentColor"
+            strokeWidth={1.5}
+            aria-hidden="true"
+          >
+            <path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              d="M19 7l-.867 12.142A2 2 0 0116.138 21H7.862a2 2 0 01-1.995-1.858L5 7m5 4v6m4-6v6m1-10V4a1 1 0 00-1-1h-4a1 1 0 00-1 1v3M4 7h16"
+            />
+          </svg>
+        </button>
+      </div>
+    </div>
+  )
+}

src/env.ts

@@ -0,0 +1,15 @@
+import { createEnv } from '@t3-oss/env-core'
+import { z } from 'zod'
+
+export const env = createEnv({
+  server: {
+    DATABASE_URL: z.url({ protocol: /^postgres(ql)?$/ }),
+    LOG_DB: z.stringbool().default(false),
+    LOG_FORMAT: z.enum(['pretty', 'json']).optional(),
+    LOG_LEVEL: z.enum(['trace', 'debug', 'info', 'warning', 'error', 'fatal']).default('info'),
+  },
+  clientPrefix: 'VITE_',
+  client: {},
+  runtimeEnv: process.env,
+  emptyStringAsUndefined: true,
+})

src/routeTree.gen.ts

@@ -9,21 +9,21 @@
 // Additionally, you should also exclude this file from your linter and/or formatter to prevent it from being checked or modified.
 
 import { Route as rootRouteImport } from './routes/__root'
+import { Route as HealthRouteImport } from './routes/health'
 import { Route as IndexRouteImport } from './routes/index'
-import { Route as ApiHealthRouteImport } from './routes/api/health'
 import { Route as ApiSplatRouteImport } from './routes/api/$'
 import { Route as ApiRpcSplatRouteImport } from './routes/api/rpc.$'
 
+const HealthRoute = HealthRouteImport.update({
+  id: '/health',
+  path: '/health',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const IndexRoute = IndexRouteImport.update({
   id: '/',
   path: '/',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiHealthRoute = ApiHealthRouteImport.update({
-  id: '/api/health',
-  path: '/api/health',
-  getParentRoute: () => rootRouteImport,
-} as any)
 const ApiSplatRoute = ApiSplatRouteImport.update({
   id: '/api/$',
   path: '/api/$',
@@ -37,40 +37,47 @@ const ApiRpcSplatRoute = ApiRpcSplatRouteImport.update({
 
 export interface FileRoutesByFullPath {
   '/': typeof IndexRoute
+  '/health': typeof HealthRoute
   '/api/$': typeof ApiSplatRoute
-  '/api/health': typeof ApiHealthRoute
   '/api/rpc/$': typeof ApiRpcSplatRoute
 }
 export interface FileRoutesByTo {
   '/': typeof IndexRoute
+  '/health': typeof HealthRoute
   '/api/$': typeof ApiSplatRoute
-  '/api/health': typeof ApiHealthRoute
   '/api/rpc/$': typeof ApiRpcSplatRoute
 }
 export interface FileRoutesById {
   __root__: typeof rootRouteImport
   '/': typeof IndexRoute
+  '/health': typeof HealthRoute
   '/api/$': typeof ApiSplatRoute
-  '/api/health': typeof ApiHealthRoute
   '/api/rpc/$': typeof ApiRpcSplatRoute
 }
 export interface FileRouteTypes {
   fileRoutesByFullPath: FileRoutesByFullPath
-  fullPaths: '/' | '/api/$' | '/api/health' | '/api/rpc/$'
+  fullPaths: '/' | '/health' | '/api/$' | '/api/rpc/$'
   fileRoutesByTo: FileRoutesByTo
-  to: '/' | '/api/$' | '/api/health' | '/api/rpc/$'
+  to: '/' | '/health' | '/api/$' | '/api/rpc/$'
-  id: '__root__' | '/' | '/api/$' | '/api/health' | '/api/rpc/$'
+  id: '__root__' | '/' | '/health' | '/api/$' | '/api/rpc/$'
   fileRoutesById: FileRoutesById
 }
 export interface RootRouteChildren {
   IndexRoute: typeof IndexRoute
+  HealthRoute: typeof HealthRoute
   ApiSplatRoute: typeof ApiSplatRoute
-  ApiHealthRoute: typeof ApiHealthRoute
   ApiRpcSplatRoute: typeof ApiRpcSplatRoute
 }
 
 declare module '@tanstack/react-router' {
   interface FileRoutesByPath {
+    '/health': {
+      id: '/health'
+      path: '/health'
+      fullPath: '/health'
+      preLoaderRoute: typeof HealthRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/': {
       id: '/'
       path: '/'
@@ -78,13 +85,6 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof IndexRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/health': {
-      id: '/api/health'
-      path: '/api/health'
-      fullPath: '/api/health'
-      preLoaderRoute: typeof ApiHealthRouteImport
-      parentRoute: typeof rootRouteImport
-    }
     '/api/$': {
       id: '/api/$'
       path: '/api/$'
@@ -104,8 +104,8 @@ declare module '@tanstack/react-router' {
 
 const rootRouteChildren: RootRouteChildren = {
   IndexRoute: IndexRoute,
+  HealthRoute: HealthRoute,
   ApiSplatRoute: ApiSplatRoute,
-  ApiHealthRoute: ApiHealthRoute,
   ApiRpcSplatRoute: ApiRpcSplatRoute,
 }
 export const routeTree = rootRouteImport

src/routes/__root.tsx

@@ -4,6 +4,7 @@ import { ReactQueryDevtoolsPanel } from '@tanstack/react-query-devtools'
 import { createRootRouteWithContext, HeadContent, Scripts } from '@tanstack/react-router'
 import { TanStackRouterDevtoolsPanel } from '@tanstack/react-router-devtools'
 import type { ReactNode } from 'react'
+import { name } from '#package'
 import { ErrorComponent } from '@/components/Error'
 import { NotFoundComponent } from '@/components/NotFound'
 import appCss from '@/styles.css?url'
@@ -23,7 +24,7 @@ export const Route = createRootRouteWithContext<RouterContext>()({
         content: 'width=device-width, initial-scale=1',
       },
       {
-        title: 'Furtherverse',
+        title: name,
       },
     ],
     links: [
@@ -34,8 +35,8 @@ export const Route = createRootRouteWithContext<RouterContext>()({
     ],
   }),
   shellComponent: RootDocument,
-  errorComponent: () => <ErrorComponent />,
+  errorComponent: ErrorComponent,
-  notFoundComponent: () => <NotFoundComponent />,
+  notFoundComponent: NotFoundComponent,
 })
 
 function RootDocument({ children }: Readonly<{ children: ReactNode }>) {

src/routes/api/$.ts

@@ -3,7 +3,7 @@ import { OpenAPIReferencePlugin } from '@orpc/openapi/plugins'
 import { onError } from '@orpc/server'
 import { ZodToJsonSchemaConverter } from '@orpc/zod/zod4'
 import { createFileRoute } from '@tanstack/react-router'
-import { name, version } from '@/../package.json'
+import { name, version } from '#package'
 import { handleValidationError, logError } from '@/server/api/interceptors'
 import { router } from '@/server/api/routers'
 

src/routes/health.ts

@@ -0,0 +1,9 @@
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/health')({
+  server: {
+    handlers: {
+      GET: () => new Response('ok', { status: 200, headers: { 'content-type': 'text/plain' } }),
+    },
+  },
+})

src/routes/index.tsx

@@ -0,0 +1,87 @@
+import { useMutation, useSuspenseQuery } from '@tanstack/react-query'
+import { createFileRoute } from '@tanstack/react-router'
+import { orpc } from '@/client/orpc'
+import { useInvalidateTodos } from '@/client/queries/todo'
+import { TodoForm } from '@/components/TodoForm'
+import { TodoItem } from '@/components/TodoItem'
+
+export const Route = createFileRoute('/')({
+  component: Todos,
+  loader: async ({ context }) => {
+    await context.queryClient.ensureQueryData(orpc.todo.list.queryOptions())
+  },
+})
+
+function Todos() {
+  const listQuery = useSuspenseQuery(orpc.todo.list.queryOptions())
+  const invalidateTodos = useInvalidateTodos()
+
+  const createMutation = useMutation(orpc.todo.create.mutationOptions({ onSuccess: invalidateTodos }))
+  const updateMutation = useMutation(orpc.todo.update.mutationOptions({ onSuccess: invalidateTodos }))
+  const deleteMutation = useMutation(orpc.todo.remove.mutationOptions({ onSuccess: invalidateTodos }))
+
+  const todos = listQuery.data
+  const completedCount = todos.filter((todo) => todo.completed).length
+  const totalCount = todos.length
+  const progress = totalCount > 0 ? (completedCount / totalCount) * 100 : 0
+
+  return (
+    <div className="min-h-screen bg-slate-50 py-12 px-4 sm:px-6 font-sans">
+      <div className="max-w-2xl mx-auto space-y-8">
+        <div className="flex items-end justify-between">
+          <div>
+            <h1 className="text-3xl font-bold text-slate-900 tracking-tight">我的待办</h1>
+            <p className="text-slate-500 mt-1">保持专注，逐个击破</p>
+          </div>
+          <div className="text-right">
+            <div className="text-2xl font-semibold text-slate-900">
+              {completedCount}
+              <span className="text-slate-400 text-lg">/{totalCount}</span>
+            </div>
+            <div className="text-xs font-medium text-slate-400 uppercase tracking-wider">已完成</div>
+          </div>
+        </div>
+
+        <TodoForm onSubmit={(title) => createMutation.mutate({ title })} isPending={createMutation.isPending} />
+
+        {totalCount > 0 && (
+          <div className="h-1.5 w-full bg-slate-200 rounded-full overflow-hidden">
+            <div
+              className="h-full bg-indigo-500 transition-all duration-500 ease-out rounded-full"
+              style={{ width: `${progress}%` }}
+            />
+          </div>
+        )}
+
+        <div className="space-y-3">
+          {todos.length === 0 ? (
+            <div className="py-20 text-center">
+              <div className="inline-flex items-center justify-center w-16 h-16 rounded-full bg-slate-100 mb-4">
+                <svg
+                  className="w-8 h-8 text-slate-400"
+                  fill="none"
+                  viewBox="0 0 24 24"
+                  stroke="currentColor"
+                  aria-hidden="true"
+                >
+                  <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M12 6v6m0 0v6m0-6h6m-6 0H6" />
+                </svg>
+              </div>
+              <p className="text-slate-500 text-lg font-medium">没有待办事项</p>
+              <p className="text-slate-400 text-sm mt-1">输入上方内容添加您的第一个任务</p>
+            </div>
+          ) : (
+            todos.map((todo) => (
+              <TodoItem
+                key={todo.id}
+                todo={todo}
+                onToggle={(id, completed) => updateMutation.mutate({ id, data: { completed: !completed } })}
+                onDelete={(id) => deleteMutation.mutate({ id })}
+              />
+            ))
+          )}
+        </div>
+      </div>
+    </div>
+  )
+}

src/server/api/context.ts

@@ -0,0 +1,3 @@
+export interface BaseContext {
+  headers: Headers
+}

src/server/api/contracts/todo.contract.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, test } from 'bun:test'
+import { createInsertSchema } from 'drizzle-zod'
+import { generatedFieldKeys } from '@/server/db/fields'
+import { todoTable } from '@/server/db/schema'
+
+describe('todo insert schema', () => {
+  const insertSchema = createInsertSchema(todoTable).omit(generatedFieldKeys)
+
+  test('accepts a minimal valid input', () => {
+    expect(insertSchema.safeParse({ title: 'buy milk' }).success).toBe(true)
+  })
+
+  test('rejects missing title', () => {
+    expect(insertSchema.safeParse({}).success).toBe(false)
+  })
+
+  test('rejects non-string title', () => {
+    expect(insertSchema.safeParse({ title: 42 }).success).toBe(false)
+  })
+})

src/server/api/contracts/todo.contract.ts

@@ -1,5 +1,5 @@
 import { oc } from '@orpc/contract'
-import { createInsertSchema, createSelectSchema, createUpdateSchema } from 'drizzle-orm/zod'
+import { createInsertSchema, createSelectSchema, createUpdateSchema } from 'drizzle-zod'
 import { z } from 'zod'
 import { generatedFieldKeys } from '@/server/db/fields'
 import { todoTable } from '@/server/db/schema'
@@ -8,7 +8,9 @@ const selectSchema = createSelectSchema(todoTable)
 
 const insertSchema = createInsertSchema(todoTable).omit(generatedFieldKeys)
 
-const updateSchema = createUpdateSchema(todoTable).omit(generatedFieldKeys)
+const updateSchema = createUpdateSchema(todoTable)
+  .omit(generatedFieldKeys)
+  .refine((data) => Object.keys(data).length > 0, { message: 'At least one field is required' })
 
 export const list = oc.input(z.void()).output(z.array(selectSchema))
 

src/server/api/interceptors.ts

@@ -1,13 +1,19 @@
 import { ORPCError, ValidationError } from '@orpc/server'
 import { z } from 'zod'
+import { getLogger } from '@/server/logger'
+
+const logger = getLogger(['api'])
 
 export const logError = (error: unknown) => {
-  console.error(error)
+  logger.error('Unhandled error in ORPC handler', { error })
 }
 
 export const handleValidationError = (error: unknown) => {
-  if (error instanceof ORPCError && error.code === 'BAD_REQUEST' && error.cause instanceof ValidationError) {
+  if (!(error instanceof ORPCError) || !(error.cause instanceof ValidationError)) return
-    // If you only use Zod you can safely cast to ZodIssue[] (per ORPC official docs)
+
+  if (error.code === 'BAD_REQUEST') {
+    // ORPC widens issues to the Standard Schema shape; every contract here is built from Zod/drizzle-zod,
+    // so the runtime objects are Zod issues. Rehydrate to reuse z.prettifyError / z.flattenError.
     const zodError = new z.ZodError(error.cause.issues as z.core.$ZodIssue[])
 
     throw new ORPCError('INPUT_VALIDATION_FAILED', {
@@ -18,7 +24,7 @@ export const handleValidationError = (error: unknown) => {
     })
   }
 
-  if (error instanceof ORPCError && error.code === 'INTERNAL_SERVER_ERROR' && error.cause instanceof ValidationError) {
+  if (error.code === 'INTERNAL_SERVER_ERROR') {
     throw new ORPCError('OUTPUT_VALIDATION_FAILED', {
       cause: error.cause,
     })

src/server/api/routers/index.ts

@@ -1,4 +1,4 @@
-import { os } from '../server'
+import { os } from '@/server/api/server'
 import * as todo from './todo.router'
 
 export const router = os.router({

src/server/api/routers/todo.router.ts

@@ -0,0 +1,39 @@
+import { ORPCError } from '@orpc/server'
+import { eq } from 'drizzle-orm'
+import { os } from '@/server/api/server'
+import { db } from '@/server/db'
+import { todoTable } from '@/server/db/schema'
+
+export const list = os.todo.list.handler(async () => {
+  return db.query.todoTable.findMany({
+    orderBy: (table, { desc }) => desc(table.createdAt),
+  })
+})
+
+export const create = os.todo.create.handler(async ({ input }) => {
+  const [newTodo] = await db.insert(todoTable).values(input).returning()
+
+  if (!newTodo) {
+    throw new ORPCError('INTERNAL_SERVER_ERROR', { message: 'Failed to create todo' })
+  }
+
+  return newTodo
+})
+
+export const update = os.todo.update.handler(async ({ input }) => {
+  const [updatedTodo] = await db.update(todoTable).set(input.data).where(eq(todoTable.id, input.id)).returning()
+
+  if (!updatedTodo) {
+    throw new ORPCError('NOT_FOUND')
+  }
+
+  return updatedTodo
+})
+
+export const remove = os.todo.remove.handler(async ({ input }) => {
+  const [deleted] = await db.delete(todoTable).where(eq(todoTable.id, input.id)).returning({ id: todoTable.id })
+
+  if (!deleted) {
+    throw new ORPCError('NOT_FOUND')
+  }
+})

src/server/api/types.ts

@@ -0,0 +1,5 @@
+import type { ContractRouterClient, InferContractRouterOutputs } from '@orpc/contract'
+import type { Contract } from './contracts'
+
+export type RouterClient = ContractRouterClient<Contract>
+export type RouterOutputs = InferContractRouterOutputs<Contract>

src/server/db/fields.ts

@@ -0,0 +1,19 @@
+import { sql } from 'drizzle-orm'
+import { timestamp, uuid } from 'drizzle-orm/pg-core'
+
+export const generatedFields = {
+  id: uuid('id').primaryKey().default(sql`uuidv7()`),
+  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+  updatedAt: timestamp('updated_at', { withTimezone: true })
+    .notNull()
+    .defaultNow()
+    .$onUpdateFn(() => new Date()),
+}
+
+type GeneratedFieldKey = keyof typeof generatedFields
+
+export const generatedFieldKeys = {
+  id: true,
+  createdAt: true,
+  updatedAt: true,
+} satisfies Record<GeneratedFieldKey, true>

src/server/db/index.ts

@@ -0,0 +1,11 @@
+import { DrizzleLogger } from '@logtape/drizzle-orm'
+import { drizzle } from 'drizzle-orm/postgres-js'
+import { env } from '@/env'
+import * as schema from '@/server/db/schema'
+import { getLogger } from '@/server/logger'
+
+export const db = drizzle({
+  connection: env.DATABASE_URL,
+  schema,
+  logger: env.LOG_DB ? new DrizzleLogger(getLogger(['db']), 'info') : false,
+})

src/server/db/migrations.gen.ts

@@ -0,0 +1,8 @@
+// AUTO-GENERATED by `bun run db:embed`. Do not edit.
+import sql_0 from '#drizzle/0000_loving_thunderbird.sql' with { type: 'text' }
+
+export type EmbeddedMigration = { tag: string; sql: string; when: number; breakpoints: boolean }
+
+export const embeddedMigrations: readonly EmbeddedMigration[] = [
+  { tag: '0000_loving_thunderbird', sql: sql_0, when: 1777096386609, breakpoints: true },
+]

src/server/db/sql.d.ts

@@ -0,0 +1,4 @@
+declare module '*.sql' {
+  const content: string
+  export default content
+}

src/server/logger.ts

@@ -0,0 +1,19 @@
+import { configureSync, getConfig, getConsoleSink, getJsonLinesFormatter } from '@logtape/logtape'
+import { prettyFormatter } from '@logtape/pretty'
+import { env } from '@/env'
+
+if (getConfig() === null) {
+  const format = env.LOG_FORMAT ?? (process.stdout.isTTY ? 'pretty' : 'json')
+
+  configureSync({
+    sinks: {
+      console: getConsoleSink({ formatter: format === 'pretty' ? prettyFormatter : getJsonLinesFormatter() }),
+    },
+    loggers: [
+      { category: [], lowestLevel: env.LOG_LEVEL, sinks: ['console'] },
+      { category: ['logtape', 'meta'], lowestLevel: 'warning', sinks: ['console'], parentSinks: 'override' },
+    ],
+  })
+}
+
+export { getLogger } from '@logtape/logtape'