weifuwu 0.12.0 → 0.13.1

package/docs/ai.md

@@ -0,0 +1,93 @@
+# AI: Streaming & Workflow
+
+> [Home](../README.md) → AI
+
+## AI streaming
+
+Server-sent event streaming via the Vercel AI SDK:
+
+```ts
+import { serve, Router, aiStream } from 'weifuwu'
+import { openai } from '@ai-sdk/openai'
+
+const app = new Router()
+const chat = await aiStream(async (req, ctx) => {
+  const { messages } = await req.json()
+  return { model: openai('gpt-4o'), messages }
+})
+app.use('/chat', chat.router())
+
+serve(app.handler(), { port: 3000 })
+```
+
+## runWorkflow
+
+Multi-step DAG execution engine — packaged as a single AI SDK `Tool`. Use it with `streamText()` or `generateText()` when the LLM needs conditional logic, loops, or multi-step tool orchestration.
+
+```ts
+import { tool, streamText } from 'ai'
+import { runWorkflow } from 'weifuwu'
+import { z } from 'zod'
+
+const tools = {
+  queryUser: tool({
+    description: 'Query user info',
+    inputSchema: z.object({ userId: z.string() }),
+    execute: async ({ userId }) => ({ id: userId, email: 'user@test.com', name: 'Test' }),
+  }),
+  sendEmail: tool({
+    description: 'Send an email',
+    inputSchema: z.object({ to: z.string(), subject: z.string() }),
+    execute: async ({ to, subject }) => ({ sent: true }),
+  }),
+  runWF: runWorkflow({ tools: { queryUser, sendEmail } }),
+}
+
+// Use in any streamText call — the LLM can decide when to trigger a workflow
+const result = await streamText({
+  model,
+  tools,
+  messages: [{ role: 'user', content: '查询用户123，如果存在则发送欢迎邮件' }],
+})
+```
+
+### Node types
+
+7 built-in node types for defining the execution graph:
+
+| Node | Purpose | Input |
+|------|---------|-------|
+| `call` | Call a registered AI SDK Tool | `{ tool: "name", args: {...} }` |
+| `set` | Assign a variable | `{ name: "x", value: 42 }` |
+| `get` | Read a variable | `{ name: "x" }` |
+| `eval` | Evaluate an expression | `{ expression: "$var.x + 1" }` |
+| `if` | Conditional branch | `{ conditions: [{ test: ..., body: [nodes] }] }` |
+| `while` | Loop | `{ condition: "$var.i < 5" }, body: [nodes]` |
+| `http` | HTTP request | `{ url: "https://...", method: "GET" }` |
+
+### Reference syntax
+
+| Pattern | Meaning | Example |
+|---------|---------|---------|
+| `$var.x` | Variable `x` | `$var.counter` |
+| `$nodes.u.output` | Full output of node `u` | `$nodes.u.output` |
+| `$nodes.u.output.field` | Specific field | `$nodes.u.output.email` |
+| `$input.userId` | Input param | `$input.userId` |
+
+### LLM generation
+
+Pass a `model` to `runWorkflow` — the LLM generates the workflow JSON from a goal:
+
+```ts
+const runWF = runWorkflow({
+  tools: { queryUser, sendEmail },
+  model: openai('gpt-4o'),
+})
+
+const result = await streamText({
+  model,
+  tools: { runWF },
+})
+```
+
+The LLM calls `runWF` with a goal, and `runWorkflow` internally calls `generateText` to produce the workflow nodes, then executes them.

package/docs/extra.md

@@ -0,0 +1,67 @@
+# Health, i18n, Email & Testing
+
+> [Home](../README.md) → Extra
+
+## Health check
+
+```ts
+import { serve, Router, health } from 'weifuwu'
+
+const app = new Router()
+app.use(health())                              // GET /health → 200
+app.use(health({ path: '/healthz' }))          // custom path
+app.use(health({
+  check: async () => { await db.sql`SELECT 1` },  // fail → 503
+}))
+serve(app.handler(), { port: 3000 })
+```
+
+Returns a `Router` — mount with `app.use()`.
+
+## Internationalization
+
+```ts
+import { i18n } from 'weifuwu'
+
+app.use(i18n({ dir: './locales', defaultLocale: 'en' }))
+
+// In any handler after i18n middleware:
+app.get('/hello', (req, ctx) => {
+  const msg = ctx.t('greeting', { name: 'World' })
+  return Response.json({ message: msg, locale: ctx.locale })
+})
+```
+
+Locale detection: `Cookie: locale=zh` → `Accept-Language: zh-CN` → `defaultLocale`.
+
+## Email
+
+```ts
+import { mailer } from 'weifuwu'
+
+// SMTP transport
+const mail = mailer({
+  transport: 'smtp://user:pass@smtp.example.com',
+  from: 'noreply@example.com',
+})
+await mail.send({ to: 'user@example.com', subject: 'Welcome', html: '<h1>Hi!</h1>' })
+await mail.close()
+
+// Custom transport (Resend, SES, SendGrid, etc.)
+const mail2 = mailer({
+  send: async (msg) => { await resend.emails.send(msg) },
+})
+await mail2.send({ to: 'user@example.com', subject: 'Hi', text: 'Hello' })
+await mail2.close()
+```
+
+## Test utilities
+
+```ts
+import { createTestServer } from 'weifuwu'
+
+const { server, url } = await createTestServer(app.handler())
+const res = await fetch(`${url}/api/users`)
+assert.equal(res.status, 200)
+server.stop()
+```

package/docs/graphql.md

@@ -0,0 +1,61 @@
+# GraphQL
+
+> [Home](../README.md) → GraphQL
+
+## 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/messager.md

@@ -0,0 +1,48 @@
+# Messager
+
+> [Home](../README.md) → Messager
+
+## Messager
+
+Real-time chat with channels, WebSocket, and agent routing.
+
+```ts
+import { messager, agent } from 'weifuwu'
+
+const agents = agent({ pg })
+const msg = messager({ pg, agents })
+
+await msg.migrate()
+app.use('/api', msg.router())
+app.ws('/ws', u.middleware(), msg.wsHandler())
+```
+
+### Channels
+
+```http
+POST   /channels            name, type (channel|dm), members
+GET    /channels
+GET    /channels/:id
+```
+
+### Messages
+
+```http
+GET  /channels/:id/messages     ?limit=50&before={id}
+POST /channels/:id/messages     content, sender_type, type
+POST /channels/:id/read         last_message_id
+```
+
+### 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' })
+```

package/docs/middleware.md

@@ -0,0 +1,131 @@
+# Middleware
+
+> [Home](../README.md) → Middleware
+
+## Built-in middleware
+
+### Auth
+
+```ts
+import { auth } from 'weifuwu'
+
+// Static bearer token
+app.use(auth({ token: 'sk-123' }))
+
+// Custom verify (JWT, DB, etc.) — return object to set ctx.user
+app.use(auth({
+  verify: async (token) => {
+    const user = await db.findUserByToken(token)
+    return user ? { sub: user.id, role: user.role } : null
+  },
+}))
+
+// Proxy validation to external auth service
+app.get('/protected', auth({ proxy: 'http://auth:3000/validate' }), handler)
+
+// Custom header
+app.use(auth({ header: 'X-API-Key', token: 'my-key' }))
+```
+
+### CORS
+
+```ts
+import { cors } from 'weifuwu'
+
+app.use(cors())                                          // allow all
+app.use(cors({ origin: ['https://example.com'] }))       // whitelist
+app.use(cors({ origin: (o) => o.endsWith('.trusted.com') ? o : false }))
+app.use(cors({ credentials: true, maxAge: 3600 }))
+```
+
+### Logger
+
+```ts
+import { logger } from 'weifuwu'
+
+app.use(logger())                           // GET /hello 200 5ms
+app.use(logger({ format: 'combined' }))     // with query params
+```
+
+### Rate limit
+
+```ts
+import { rateLimit } from 'weifuwu'
+
+app.use(rateLimit({ max: 100, window: 60_000 }))          // 100 req/min
+app.get('/api', rateLimit({ max: 10 }), handler)          // per-route
+
+// Custom key (by API key, user ID, etc.)
+app.use(rateLimit({
+  max: 1000,
+  key: (req) => req.headers.get('x-api-key') ?? 'anonymous',
+}))
+```
+
+### Compression
+
+```ts
+import { compress } from 'weifuwu'
+
+app.use(compress())                       // brotli > gzip > deflate
+app.use(compress({ threshold: 2048 }))    // only compress > 2KB
+```
+
+## Validation
+
+```ts
+import { z } from 'zod'
+import { validate } from 'weifuwu'
+
+const CreateUser = z.object({
+  name: z.string().min(1),
+  email: z.string().email(),
+})
+
+router.post('/users',
+  validate({ body: CreateUser }),
+  (req, ctx) => {
+    // ctx.parsed.body — typed & validated
+  },
+)
+```
+
+## File upload
+
+```ts
+import { upload } from 'weifuwu'
+
+router.post('/upload',
+  upload({ dir: './uploads', maxFileSize: 10_485_760 }),
+  (req, ctx) => {
+    // ctx.parsed.files.avatar  → { name, type, size, path }
+    // ctx.parsed.fields.title  → 'hello'
+  },
+)
+```
+
+## Cookie
+
+```ts
+import { getCookies, setCookie, deleteCookie } from 'weifuwu'
+
+// Read
+const cookies = getCookies(req)        // { session: 'abc' }
+
+// Set (immutable — returns new Response)
+let res = new Response('ok')
+res = setCookie(res, 'session', 'token', { httpOnly: true, secure: true, maxAge: 3600 })
+
+// Delete
+res = deleteCookie(res, 'session')
+```
+
+## Static files
+
+```ts
+import { serveStatic } from 'weifuwu'
+
+router.get('/static/*', serveStatic('./public'))
+```
+
+Features: MIME type detection (20+ types), ETag + If-None-Match (304), directory index (index.html), path traversal protection, Cache-Control.

package/docs/opencode.md

@@ -0,0 +1,252 @@
+# Opencode
+
+> [Home](../README.md) → Opencode
+
+## Opencode
+
+AI programming assistant — chat with LLM agents that have access to filesystem tools, skills, and isolated session workspaces.
+
+```ts
+import { serve, Router, postgres, opencode } from 'weifuwu'
+
+const app = new Router()
+const pg = postgres()
+const oc = await opencode({ pg, permissions: { ... } })
+
+await oc.migrate()
+app.use('/opencode', await oc.router())
+app.ws('/opencode', oc.wsHandler())
+
+serve(app.handler(), { port: 3000, websocket: app.websocketHandler() })
+```
+
+### Session-isolated workspaces
+
+Each session gets its own sandbox directory — tools operate within it, files cannot escape:
+
+```
+cwd/.sessions/opencode/1/    ← session 1's workspace
+cwd/.sessions/opencode/2/    ← session 2's workspace
+cwd/.sessions/chat/3/        ← different mount point
+```
+
+Workspaces are computed from `cwd { ctx.mountPath } { sessionId }`. The system prompt shows the session's workspace so the LLM knows where it is.
+
+### Tools
+
+| Tool | Description |
+|------|-------------|
+| `bash` | Execute shell commands in the workspace |
+| `read` | Read files with offset/limit |
+| `write` | Create or overwrite files |
+| `edit` | Exact string replacements |
+| `grep` | Regex content search |
+| `glob` | Glob pattern file search |
+| `web` | Fetch URL content |
+| `question` | Ask the user for input |
+| `skill` | Load a skill on demand |
+
+### Skills
+
+Skills are discovered from filesystem and loaded on demand via the `skill` tool — no system prompt bloat:
+
+- Project: `.opencode/skills/{name}/SKILL.md`
+- Global: `~/.config/opencode/skills/{name}/SKILL.md`
+- Also reads: `.claude/skills/`, `.agents/skills/` (project + global)
+
+```ts
+const oc = await opencode({
+  pg,
+  skills: [{ name: 'git', description: 'Git workflow', content: '...' }],
+})
+```
+
+### Permissions
+
+Control tool access per conversation:
+
+```ts
+const oc = await opencode({
+  pg,
+  permissions: {
+    bash: { allow: true },
+    read: { allow: true },
+    write: { allow: false },
+    edit: { allow: false },
+    skill: { '*': { allow: true }, 'internal-*': { allow: false } },
+  },
+})
+```
+
+### Workspace isolation
+
+```ts
+const oc = await opencode({ pg, permissions })
+// All sessions inherit the instance's workspace (default: process.cwd())
+// Sessions cannot override their workspace
+// Different mount points = different opencode() instances = isolated workspaces
+```
+
+```ts
+import { serve, Router, postgres, user } from 'weifuwu'
+
+const app = new Router()
+const pg = postgres()
+await pg.migrate()
+
+const auth = user({ pg, jwtSecret: process.env.JWT_SECRET! })
+
+// POST /auth/register  { email, password, name }
+// POST /auth/login     { email, password }
+// GET  /auth/oauth/authorize?client_id=...&redirect_uri=...&response_type=code
+// POST /auth/oauth/consent
+// POST /auth/oauth/token  (grant_type=authorization_code|client_credentials)
+app.use('/auth', auth.router())
+
+// Protected routes — verifies JWT, sets ctx.user
+app.get('/me', auth.middleware(), async (req, ctx) => {
+  return Response.json(ctx.user)
+  // { id, email, name, role }
+})
+```
+
+Password hashing uses `crypto.scryptSync` + `timingSafeEqual` (Node.js built-in, zero deps). JWT tokens use the `jsonwebtoken` package. The users table (`_users` by default) is auto-created on first `migrate()`.
+
+### OAuth2 Server
+
+Enable OAuth2 Server to let third-party apps (SPA, mobile, microservices) authenticate users through your app.
+
+```ts
+const auth = user({
+  pg,
+  jwtSecret: process.env.JWT_SECRET!,
+  oauth2: { server: true },
+})
+
+await auth.migrate()  // creates _users + _oauth2_clients + _oauth2_codes + _oauth2_tokens
+
+// Register a client app (programmatic — CLI, admin UI, seed script)
+const client = await auth.registerClient({
+  name: 'My SPA',
+  redirectUris: ['https://myapp.com/callback'],
+})
+// → { clientId, clientSecret, name, redirectUris }
+
+// Use auth middleware to protect routes — OAuth2 JWT tokens work seamlessly
+app.get('/api/data', auth.middleware(), handler)
+```
+
+#### Supported Grant Types
+
+| Grant | Use Case | PKCE |
+|-------|----------|------|
+| `authorization_code` (with client_secret) | Server-side apps | Optional |
+| `authorization_code` (with `code_challenge`/`code_verifier`) | SPA / Mobile apps | Required |
+| `client_credentials` | Machine-to-machine | — |
+
+#### Flow (Authorization Code + PKCE)
+
+```
+1. 第三方 App 引导用户:
+    GET /oauth/authorize?client_id=xxx&redirect_uri=https://app.com/cb
+                       &response_type=code&code_challenge=S256&state=yyy
+
+2. 用户未登录 → 302 到 /login?redirect=... → 登录后自动回到授权页
+
+3. 用户确认授权 → POST /oauth/consent { approve: true, client_id, ... }
+   302 redirect_uri?code=xxx&state=yyy
+
+4. 第三方 App POST /oauth/token
+   { grant_type: authorization_code, code, client_id, client_secret,
+     redirect_uri, code_verifier }
+   → { access_token, token_type: "Bearer", expires_in, refresh_token }
+
+5. access_token 是标准 JWT，auth.middleware() 和 auth.verify() 直接可用
+```
+
+#### Client Management
+
+```ts
+const client  = await auth.registerClient({ name, redirectUris })
+const found   = await auth.getClient(client.clientId)
+await auth.revokeClient(client.clientId)
+```
+
+#### Using OAuth2 Tokens with the Built-in Auth Middleware
+
+OAuth2 Server 签发的 `access_token` 与密码登录的 JWT 使用同一 `jwtSecret`，payload 向下兼容（`sub`、`email`、`role`），所以 `auth()` 无需任何修改即可验证 OAuth2 签发的 token：
+
+```ts
+import { auth } from 'weifuwu'
+
+// 同一个 auth() 中间件同时支持密码登录 JWT 和 OAuth2 JWT
+app.get('/api', auth({ verify: (token) => auth.verify(token) }), handler)
+```
+
+For `client_credentials` tokens (machine-to-machine), `verify()` returns `null` since no user is associated.
+
+### Social Login (GitHub) — Cookbook
+
+`user()` 不内置 social login（避免绑定第三方平台），但用底层 API 加一个 GitHub 登录只需 ~30 行：
+
+```ts
+import { user } from 'weifuwu'
+import jwt from 'jsonwebtoken'
+
+const auth = user({ pg, jwtSecret })
+
+// 1. 跳转 GitHub 授权
+app.get('/auth/github', () => {
+  const url = new URL('https://github.com/login/oauth/authorize')
+  url.searchParams.set('client_id', process.env.GH_CLIENT_ID!)
+  url.searchParams.set('redirect_uri', 'http://localhost:3000/auth/github/callback')
+  url.searchParams.set('scope', 'user:email')
+  return Response.redirect(url.href)
+})
+
+// 2. GitHub 回调 → 获取用户信息 → 注册/登录
+app.get('/auth/github/callback', async (req) => {
+  const { code } = Object.fromEntries(new URL(req.url).searchParams)
+  if (!code) return new Response('Missing code', { status: 400 })
+
+  // 交换 token
+  const tokenRes = await fetch('https://github.com/login/oauth/access_token', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+    body: JSON.stringify({
+      client_id: process.env.GH_CLIENT_ID,
+      client_secret: process.env.GH_CLIENT_SECRET,
+      code,
+    }),
+  })
+  const { access_token } = await tokenRes.json() as any
+
+  // 获取用户信息
+  const userRes = await fetch('https://api.github.com/user', {
+    headers: { Authorization: `Bearer ${access_token}` },
+  })
+  const ghUser = await userRes.json() as any
+
+  // 查找或创建本地用户
+  const existing = await pg.sql`SELECT * FROM "_users" WHERE email = ${ghUser.email}`
+  let localUser = existing[0]
+
+  if (!localUser) {
+    localUser = await auth.register({
+      email: ghUser.email,
+      password: crypto.randomUUID(),  // 随机密码，用户只能用 GitHub 登录
+      name: ghUser.name ?? ghUser.login,
+    })
+  }
+
+  // 签发 JWT（与 user() 同一格式）
+  const token = jwt.sign(
+    { sub: localUser.id, email: localUser.email, role: localUser.role ?? 'user' },
+    process.env.JWT_SECRET!,
+    { expiresIn: '24h' },
+  )
+  return Response.json({ token })
+})
+```
+
+同样的模式适配 Google、微信、任何 OAuth2 provider。