weifuwu 0.12.0 → 0.13.1

package/docs/postgres.md

@@ -0,0 +1,162 @@
+# PostgreSQL
+
+> [Home](../README.md) → PostgreSQL
+
+## PostgreSQL
+
+Built-in PostgreSQL client — connection management, type-safe DDL, transactions, and module lifecycle.
+
+```ts
+import { serve, Router, postgres } from 'weifuwu'
+
+const app = new Router()
+const pg = postgres()          // reads DATABASE_URL
+app.use(pg)                     // injects ctx.sql into handlers
+```
+
+### Type-safe DDL with schema builder
+
+Define tables declaratively with type inference — no raw SQL for common operations, no Zod needed:
+
+```ts
+import { pgTable, serial, uuid, text, integer, boolean, timestamptz, jsonb, sql } from 'weifuwu'
+
+const users = pgTable('_users', {
+  id:        serial('id').primaryKey(),
+  name:      text('name').notNull(),
+  email:     text('email').unique().notNull(),
+  age:       integer('age'),
+  active:    boolean('active').default(true),
+  createdAt: timestamptz('created_at').default(sql`NOW()`),
+  metadata:  jsonb<{ role: string }>('metadata'),
+})
+```
+
+Supports 10 column types:
+| Builder | DDL | TS Type |
+|---------|-----|---------|
+| `serial()` | `SERIAL` | `number` |
+| `uuid()` | `UUID` | `string` |
+| `text()` | `TEXT` | `string` |
+| `integer()` | `INTEGER` | `number` |
+| `boolean()` | `BOOLEAN` | `boolean` |
+| `timestamptz()` | `TIMESTAMPTZ` | `string` |
+| `jsonb<T>()` | `JSONB` | `T` |
+| `textArray()` | `TEXT[]` | `string[]` |
+| `vector(name, dims)` | `vector(N)` | `number[]` |
+
+Column constraints chainable: `.primaryKey()`, `.notNull()`, `.nullable()`, `.default(value | sql\`...\`)`, `.unique()`, `.references(table, column?, onDelete?)`.
+
+### DDL execution
+
+```ts
+await users.create()                         // CREATE TABLE IF NOT EXISTS
+await users.createIndex('email')             // CREATE INDEX
+await users.createUniqueIndex('slug')        // CREATE UNIQUE INDEX
+await users.createIndex('created_at', { desc: true })
+await users.createIndex(['a', 'b'])          // multi-column
+await users.createIndex('embedding', {       // pgvector HNSW
+  type: 'hnsw', operator: 'vector_cosine_ops',
+})
+await users.drop({ cascade: true })
+```
+
+### Type-safe CRUD with BoundTable
+
+Two usage paths — use `pg.table()` when you have a `pg` handle, or `pgTable()` with explicit `sql`:
+
+```ts
+// pg.table() — auto-binds sql, no need to pass it
+const users = pg.table('_users', {
+  id:        serial('id').primaryKey(),
+  name:      text('name').notNull(),
+  email:     text('email').unique(),
+  active:    boolean('active').default(true),
+  createdAt: timestamptz('created_at').default(sql`NOW()`),
+})
+
+// INSERT ... RETURNING * — auto-strips serial id
+const user = await users.insert({ name: 'Alice', email: 'alice@test.com' })
+// → { id: 1, name: 'Alice', email: 'alice@test.com', active: true, ... }
+
+// SELECT ... WHERE id = ? LIMIT 1
+const found = await users.findById(1)
+
+// SELECT ... WHERE ... [ORDER BY ...] [LIMIT ...] [OFFSET ...]
+const admins = await users.find({ role: 'admin' })
+const sorted = await users.find({ active: true }, { orderBy: { name: 'asc' } })
+const page = await users.find(undefined, { limit: 10, offset: 0 })
+const filtered = await users.find({ role: 'admin' }, { orderBy: { name: 'desc' }, limit: 5 })
+
+// UPDATE ... SET ... WHERE ... RETURNING *
+const updated = await users.update({ id: 1 }, { name: 'Bob' })
+// With SQL expressions:
+await users.update({ id: 1 }, { name: 'Bob', updated_at: sql`NOW()` })
+
+// DELETE ... WHERE ... RETURNING 1
+const ok = await users.delete({ id: 1 })
+```
+
+When using `pgTable()` directly (without `pg`), pass `sql` as the first argument:
+
+```ts
+const t = pgTable('_users', { ... })
+await t.insert(ctx.sql, { name: 'Alice' })
+await t.find(ctx.sql, { role: 'admin' }, { orderBy: { name: 'asc' } })
+```
+
+### Complex queries use raw SQL
+
+```ts
+app.get('/users/stats', async (req, ctx) => {
+  const rows = await ctx.sql`
+    SELECT u.*, count(p.id) as posts
+    FROM ${users} u LEFT JOIN posts p ON p.user_id = u.id
+    GROUP BY u.id
+  `
+  return Response.json(rows)
+})
+```
+
+### Transactions
+
+```ts
+const result = await pg.transaction(async (tx) => {
+  const [user] = await tx`INSERT INTO "_users" (...) VALUES (...) RETURNING *`
+  const [wallet] = await tx`INSERT INTO "_wallets" ("user_id") VALUES (${user.id}) RETURNING *`
+  return { user, wallet }
+})
+```
+
+### Connection lifecycle
+
+```ts
+const pg = postgres()                          // reads DATABASE_URL
+const pg = postgres('postgres://...')          // explicit connection
+const pg = postgres({
+  connection: 'postgres://...',
+  max: 10,                                     // pool size
+  ssl: { rejectUnauthorized: false },          // SSL options
+  idle_timeout: 30,                            // idle timeout (s)
+  connect_timeout: 10,                         // connection timeout (s)
+  closeTimeout: 5,                             // close grace period (s)
+  signal: ac.signal,                           // abort → sql.end()
+})
+await pg.close()
+```
+
+### Module base class
+
+Every database module (`opencode`, `messager`, `tenant`, `agent`, `user`) extends `PgModule`:
+
+```ts
+import { PgModule } from 'weifuwu'
+
+class MyModule extends PgModule {
+  constructor(pg: PostgresClient) {
+    super(pg)   // sets this.sql = pg.sql
+  }
+  async migrate() { /* override */ }
+  // close() inherited — calls pg.close() automatically
+}
+```

package/docs/router.md

@@ -0,0 +1,80 @@
+# Router
+
+> [Home](../README.md) → Router
+
+## Router
+
+```ts
+import { serve, Router } from 'weifuwu'
+
+const app = new Router()
+  .use((req, ctx, next) => {
+    console.log(`${req.method} ${new URL(req.url).pathname}`)
+    return next(req, ctx)
+  })
+  .get('/hello/:name', (req, ctx) =>
+    Response.json({ message: `Hello, ${ctx.params.name}!` }),
+  )
+  .post('/data', async (req, ctx) => {
+    const body = await req.json()
+    return Response.json(body, { status: 201 })
+  })
+
+serve(app.handler(), { port: 3000 })
+```
+
+## WebSocket
+
+```json
+{ "type": "message",  "channel_id": 1, "content": "Hi" }
+{ "type": "typing",   "channel_id": 1, "is_typing": true }
+{ "type": "read",     "channel_id": 1, "last_message_id": 42 }
+```
+
+### Programmatic send
+
+```ts
+await msg.send(channelId, 'System message', { sender_type: 'system' })
+```
+
+## Error handling
+
+```ts
+const app = new Router()
+  .onError((err, req, ctx) =>
+    Response.json({ error: err.message }, { status: 500 }),
+  )
+  .get('/crash', () => { throw new Error('boom') })
+```
+
+## Graceful shutdown
+
+```ts
+import { serve } from 'weifuwu'
+import type { Server } from 'weifuwu'
+
+const ac = new AbortController()
+let server: Server
+
+process.on('SIGTERM', () => {
+  ac.abort()
+  server.stop()
+})
+
+server = serve((req, ctx) => new Response('Hello'), {
+  port: 3000,
+  signal: ac.signal,
+})
+await server.ready
+```
+
+### Using with WebSocket
+
+```ts
+const app = new Router().ws('/chat', { … })
+const server = serve(app.handler(), {
+  port: 3000,
+  signal: ac.signal,
+  websocket: app.websocketHandler(),
+})
+```

package/docs/tenant.md

@@ -0,0 +1,174 @@
+# Tenant BaaS
+
+> [Home](../README.md) → Tenant BaaS
+
+## Tenant BaaS
+
+Built-in multi-tenant backend-as-a-service — define tables at runtime via API, get RESTful CRUD + GraphQL automatically, with row-level tenant isolation.
+
+```ts
+import { serve, Router, postgres, user, tenant } from 'weifuwu'
+
+const pg = postgres()
+const u = user({ pg, jwtSecret: process.env.JWT_SECRET! })
+const t = tenant({ pg, usersTable: '_users' })
+
+await pg.migrate()
+await u.migrate()
+await t.migrate()           // creates _tenants, _tenant_members, _user_tables
+
+const app = new Router()
+app.use('/auth', u.router())
+app.use('/api', u.middleware())     // → ctx.user
+app.use('/api', t.middleware())     // → ctx.tenant
+app.use('/api', t.router())        // → management + data CRUD
+app.use('/graphql', t.graphql())   // → dynamic GraphQL
+```
+
+### System tables
+
+| Table | Purpose |
+|-------|---------|
+| `_tenants` | Tenant records (`id TEXT PK DEFAULT gen_random_uuid()`, `name`, `created_at`) |
+| `_tenant_members` | User-tenant membership (`tenant_id`, `user_id`, `role`) |
+| `_user_tables` | Dynamic table definitions (`tenant_id`, `slug`, `fields JSONB`) |
+
+### Dynamic table API
+
+Create a table at runtime:
+
+```json
+POST /api/tables
+{
+  "slug": "articles",
+  "fields": [
+    { "name": "title", "type": "string", "required": true },
+    { "name": "content", "type": "text" },
+    { "name": "status", "type": "enum", "options": ["draft", "published"], "default": "draft" },
+    { "name": "views", "type": "integer", "default": 0 },
+    { "name": "embedding", "type": "vector", "dimensions": 1536, "index": "hnsw" }
+  ]
+}
+```
+
+→ Creates a PostgreSQL table with `id SERIAL PK`, `tenant_id TEXT NOT NULL`, and the specified columns, plus indexes. The table name is internally scoped to the tenant.
+
+### Field types
+
+| type | PostgreSQL | Index support |
+|------|-----------|---------------|
+| `string` | `TEXT` | `true`, `unique` |
+| `integer` | `INTEGER` | `true`, `desc`, `unique` |
+| `float` | `DOUBLE PRECISION` | `true`, `desc` |
+| `boolean` | `BOOLEAN` | `true` |
+| `text` | `TEXT` | `true` |
+| `datetime` | `TIMESTAMPTZ` | `true`, `desc` |
+| `date` | `DATE` | `true`, `desc` |
+| `enum` | `TEXT` (with validation) | `true` |
+| `json` | `JSONB` | `gin` |
+| `vector` | `vector(n)` (pgvector) | `hnsw` (HNSW, vector_cosine_ops) |
+
+### Relationships
+
+Declare a foreign key via the `relation` field:
+
+```json
+{ "name": "article_id", "type": "integer", "relation": { "table": "articles", "onDelete": "cascade" } }
+```
+
+Supported relationship patterns:
+
+| Pattern | Detection | REST | GraphQL |
+|---------|-----------|------|---------|
+| **belongs_to** | Field with `relation` | — | `comment.article` resolver |
+| **has_many** | Another table has a relation pointing here | `GET /api/articles/:id/comments` | `article.comments` resolver |
+| **M2M** | Junction table with exactly two relation fields | `GET /api/articles/:id/tags` (bypasses junction) | `article.tags` / `tag.articles` resolver |
+| **Self-ref** | Relation field pointing to same table | — | With depth control |
+
+### RESTful API
+
+All routes require `ctx.tenant` (set by `t.middleware()`). All queries automatically filter by `tenant_id`.
+
+| Route | Method | Description |
+|-------|--------|-------------|
+| `/sys/tenants` | POST | Create tenant, caller becomes admin |
+| `/sys/tenants` | GET | List user's tenants |
+| `/sys/tenants/invite` | POST | Invite user by email (admin) |
+| `/sys/tenants/members/:userId` | DELETE | Remove member (admin) |
+| `/sys/tables` | POST/GET | Create / list dynamic tables |
+| `/sys/tables/:slug` | GET/PATCH/DELETE | Get schema / add fields / drop table |
+| `/:slug` | GET | List rows (limit, offset, sort) |
+| `/:slug` | POST | Create row |
+| `/:slug/:id` | GET/PATCH/DELETE | Get / update / delete row |
+| `/:slug/:id/:_nested` | GET | List related rows (has_many / M2M) |
+| `/:slug/:id/:_nested` | POST | Create related row (auto-fills relation field) |
+
+### Vector search
+
+```http
+GET /api/articles?search_vector=[0.1,0.2,...]&search_field=embedding&search_limit=10
+```
+
+Returns rows ordered by cosine distance (`<=>`), includes `_distance` field. Supports `l2` (`<->`) and `ip` (`<#>`):
+
+```http
+GET /api/articles?search_vector=[...]&search_field=embedding&search_distance=l2
+```
+
+### GraphQL
+
+Dynamic GraphQL schema generated per-request based on the authenticated tenant's tables:
+
+```graphql
+type Article {
+  id: ID!
+  title: String!
+  content: String
+  status: String
+  comments(limit: Int, offset: Int): [Comment!]!
+}
+
+type Query {
+  articles(limit: Int, offset: Int): [Article!]!
+  getArticle(id: ID!): Article
+}
+
+type Mutation {
+  createArticle(data: CreateArticleInput!): Article!
+  updateArticle(id: ID!, data: PatchArticleInput!): Article!
+  deleteArticle(id: ID!): Boolean!
+}
+```
+
+Built with `graphql-js` native constructors (`GraphQLObjectType`), no SDL generation, no `makeExecutableSchema`.
+
+### Middleware
+
+`t.middleware()` extracts the tenant context:
+
+1. Requires `ctx.user` (from `u.middleware()`)
+2. Looks up user's tenant memberships
+3. Single tenant → automatically set `ctx.tenant`
+4. Multiple tenants → require `X-Tenant-ID` header, return 300 with tenant list if missing
+5. No tenants → 403
+
+### Tenant lifecycle
+
+```ts
+const t = tenant({ pg, usersTable: '_users' })
+
+// Create a tenant — the caller becomes admin
+const tenant = await (await fetch('http://localhost/api/sys/tenants', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer <jwt>' },
+  body: JSON.stringify({ name: 'Acme Corp' }),
+})).json()
+// → { id: "uuid", name: "Acme Corp", created_at: "..." }
+
+// Invite a member
+await fetch('http://localhost/api/sys/tenants/invite', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer <jwt>' },
+  body: JSON.stringify({ email: 'colleague@acme.com', role: 'member' }),
+})
+```

package/docs/tsx.md

@@ -0,0 +1,199 @@
+# React SSR with tsx()
+
+> [Home](../README.md) → tsx()
+
+## React pages with tsx()
+
+```ts
+import { serve, Router } from 'weifuwu'
+import { tsx } from 'weifuwu/tsx'
+
+const app = new Router()
+app.use('/', await tsx({ dir: './ui/' }))
+
+serve(app.handler(), { port: 3000, websocket: app.websocketHandler() })
+```
+
+### Directory structure
+
+```
+ui/
+├── pages/              ← 页面文件
+│   ├── page.tsx        → GET /           (React component, default export)
+│   ├── layout.tsx      → root layout     (HTML shell, receives req/ctx, NOT hydrated)
+│   ├── not-found.tsx   → 404 error page  (rendered for unmatched routes, wrapped in layout)
+│   ├── about/page.tsx  → GET /about
+│   ├── blog/[slug]/
+│   │   ├── page.tsx    → GET /blog/:slug
+│   │   ├── load.ts     → data fetching   (server-only, default export)
+│   │   └── route.ts    → POST /blog/:slug (API, named exports POST/PUT/DELETE/...)
+│   ├── blog/layout.tsx → /blog/* layout  (UI structure, receives children, hydrated)
+│   └── api/search/
+│       └── route.ts    → GET /api/search (standalone API, no page.tsx needed)
+└── components/         ← 组件文件（会被热更自动感知）
+    └── button.tsx
+```
+
+### Development mode
+
+tsx() runs in development mode automatically when `NODE_ENV !== 'production'`:
+
+- **File watching** — chokidar watches the `dir` directory for `.tsx`/`.ts` changes
+  - Page files in `pages/` → single-file recompilation + registry update
+  - Component files in `components/` → full rebuild of all pages
+  - New files are detected automatically
+- **Live reload** — Compiled via esbuild `write: false` + `vm.Script.runInContext` (no disk writes, no `node --watch` conflict)
+- **WebSocket auto-refresh** — `/__weifuwu/livereload` endpoint pushes reload signals; browser refreshes automatically
+- **`node --watch` compatible** — External files (`app.ts`, `middleware/`) handled by `--watch` restart; `ui/` changes handled by tsx() without conflict
+
+```bash
+node app.ts                # development (auto-reload + live refresh)
+NODE_ENV=production node app.ts   # production
+```
+
+### Tailwind CSS
+
+tsx() includes built-in Tailwind CSS v4 support. If an `app.css` file exists in the `dir` directory, it is compiled automatically through PostCSS + `@tailwindcss/postcss`. If no `app.css` is found, one is created automatically:
+
+```css
+@import "tailwindcss";
+```
+
+Write `className` directly in your components — no CLI, no configuration:
+
+```tsx
+export default function Home() {
+  return <h1 className="text-3xl font-bold text-blue-600">Hello</h1>
+}
+```
+
+In development mode, Tailwind is reprocessed whenever a `.tsx` file changes (new class names are picked up automatically).
+
+### `@` alias
+
+If your project has a `tsconfig.json` or `jsconfig.json` with `compilerOptions.paths`, tsx() reads it automatically and passes aliases to all esbuild builds (SSR compilation, hydration bundles, and hot reload):
+
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "@/*": ["./ui/*"]
+    }
+  }
+}
+```
+
+This enables imports like `@/components/button` or `@/lib/utils` in both server-rendered and client-hydrated code.
+
+### shadcn/ui
+
+tsx() works with [shadcn/ui](https://ui.shadcn.com) out of the box. The `@` alias and Tailwind CSS are handled automatically.
+
+```bash
+# 1. Install shadcn CLI and init (select "other" framework)
+npx shadcn@latest init
+
+# 2. When prompted, configure:
+#    - Style:            your preference
+#    - Base color:       your preference
+#    - CSS file path:    ui/app.css
+#    - Import alias:     @/  →  ./ui/
+#    - React hooks:      yes
+```
+
+```json
+// tsconfig.json (generated by shadcn init)
+{
+  "compilerOptions": {
+    "paths": {
+      "@/*": ["./ui/*"]
+    }
+  }
+}
+```
+
+Add components:
+
+```bash
+npx shadcn@latest add button card dialog
+```
+
+Use them in your pages:
+
+```tsx
+// ui/pages/page.tsx
+import { Button } from '@/components/ui/button'
+
+export default function Home() {
+  return <Button variant="outline">Click me</Button>
+}
+```
+
+```bash
+node app.ts
+```
+
+### Backward compatibility
+
+`tsx({ dir: './pages/' })` still works. When there is no `pages/` subdirectory under `dir`, the `dir` itself is used as the pages directory.
+
+### page.tsx — page component
+
+```tsx
+export default function Page({ params, query }: {
+  params: { slug: string }
+  query: Record<string, string>
+}) {
+  return <article><h1>{params.slug}</h1></article>
+}
+```
+
+### load.ts — data fetching (server-only)
+
+```ts
+export default async function load({ params, query }: {
+  params: Record<string, string>
+  query: Record<string, string>
+}) {
+  const data = await db.query(params.slug)
+  return { data }   // merged into props passed to page.tsx
+}
+```
+
+### layout.tsx
+
+**Root layout** (`pages/layout.tsx`) — receives `{ children, req, ctx }`:
+
+```tsx
+export default function RootLayout({ children, req, ctx }: {
+  children: React.ReactNode
+  req: Request
+  ctx: Context
+}) {
+  return (
+    <html>
+      <head><title>App</title></head>
+      <body><div id="__weifuwu_root">{children}</div></body>
+    </html>
+  )
+}
+```
+
+**Nested layouts** (`pages/blog/layout.tsx`) — receives only `{ children }`.
+
+### route.ts — API (co-located with page)
+
+```ts
+export const POST: Handler = async (req, ctx) => {
+  const body = await req.json()
+  return Response.json({ ...body, slug: ctx.params.slug })
+}
+```
+
+### not-found.tsx — 404 page
+
+```tsx
+export default function NotFound() {
+  return <h1 class="text-4xl">404 – Not Found</h1>
+}
+```