weifuwu 0.19.10 → 0.21.0

package/README.md

@@ -25,6 +25,17 @@ serve(app.handler(), { port: 3000, websocket: app.websocketHandler() })
 npx weifuwu init my-app && cd my-app && npm run dev
 ```
 
+## CLI
+
+```bash
+npx weifuwu init my-app              # Full project (SSR + i18n + theme + WS demo)
+npx weifuwu init my-api --minimal    # Minimal HTTP project (2 files)
+npx weifuwu init my-api --skip-install # Skip npm install
+npx weifuwu dev                       # Start dev server (auto-detect index.ts)
+npx weifuwu generate module my-mod    # Scaffold middleware module + test
+npx weifuwu version                   # Print version
+```
+
 ---
 
 ## Core Concepts
@@ -42,11 +53,14 @@ await server.ready
 | `hostname` | `string` | `'0.0.0.0'` | Listen address |
 | `signal` | `AbortSignal` | — | Shutdown on abort |
 | `websocket` | `WsUpgradeHandler` | — | WebSocket upgrade handler |
-| `maxBodySize` | `number` | — | Max body bytes |
+| `maxBodySize` | `number` | `10MB` | Max body bytes (0 = unlimited) |
+| `timeout` | `number` | `30_000` | Socket inactivity timeout (ms) |
+| `keepAliveTimeout` | `number` | `5_000` | Keep-Alive idle timeout (ms) |
+| `headersTimeout` | `number` | `6_000` | Headers read timeout (ms) |
 | `shutdown` | `boolean` | `true` | Auto SIGTERM/SIGINT |
 
 ```ts
-interface Server { stop: () => void; readonly port: number; readonly hostname: string; ready: Promise<void> }
+interface Server { stop: () => Promise<void>; readonly port: number; readonly hostname: string; ready: Promise<void> }
 const { server, url } = await createTestServer(handler)
 ```
 
@@ -58,9 +72,24 @@ app.get('/hello/:name', (req, ctx) => Response.json({ message: `Hello, ${ctx.par
 app.post('/data', async (req, ctx) => { const body = await req.json(); return Response.json(body, { status: 201 }) })
 app.use('/admin', authMW)                    // path-scoped middleware
 app.use('/admin', adminRouter)               // sub-router (flattened into parent trie)
-app.ws('/echo', { open(ws) { ws.send('connected') }, message(ws, _ctx, data) { ws.send(`echo: ${data}`) } })
+app.ws('/echo', {
+  open(ws, ctx) { ctx.ws.json({ type: 'connected' }) },
+  message(ws, ctx, data) { ctx.ws.json({ echo: data.toString() }) },
+})
+app.ws('/chat', {
+  open(ws, ctx) { ctx.ws.join('room') },
+  message(ws, ctx, data) { ctx.ws.sendRoom('room', JSON.parse(data.toString())) },
+})
 app.onError((err, req, ctx) => Response.json({ error: err.message }, { status: 500 }))
 
+// Debug: list all registered routes
+console.log(app.routes())
+// [ 'GET     /hello/:name', 'POST    /data', 'WS       /echo', 'WS       /chat' ]
+
+// Cross-process WebSocket broadcast (Redis)
+import { createHub } from 'weifuwu'
+app.wsHub(createHub({ redis: redis() }))
+
 const handler = app.handler()
 const wsHandler = app.websocketHandler()
 serve(handler, { port: 3000, websocket: wsHandler })
@@ -126,6 +155,25 @@ The `ctx` object accumulates properties as it passes through the middleware chai
 | `compiledTailwindCss` | `ssr()` internal | `string` | Compiled CSS content (internal) |
 | `tailwindCssUrl` | `ssr()` internal | `string` | Compiled CSS route URL (internal) |
 
+### Type-Safe Context
+
+Middleware-injected properties are **automatically typed** through chained `use()` calls:
+
+```ts
+const app = new Router()
+  .use(csrf())          // → Router<Context & { csrfToken: string }>
+  .use(requestId())     // → Router<Context & { csrfToken, requestId }>
+  .use(postgres())      // → Router<Context & { csrfToken, requestId, sql }>
+
+app.get('/me', (_req, ctx) => {
+  ctx.csrfToken   // ✅ string (IDE autocomplete)
+  ctx.requestId   // ✅ string
+  ctx.sql`SELECT 1` // ✅ Sql<{}>
+})
+```
+
+Each module exports an `XxxInjected` type (e.g. `PostgresInjected`, `UserInjected`) for composing custom context types. `Context` is an interface — modules augment it via `declare module` for ambient compatibility.
+
 ---
 
 ## Module Patterns
@@ -165,6 +213,98 @@ app.use('/', a)           // dashboard
 
 ---
 
+## Request Tracing & Logging
+
+Every request gets a **trace ID** via `AsyncLocalStorage`, injected into responses as `X-Trace-Id`. W3C `traceparent` headers are forwarded.
+
+```ts
+import { currentTraceId } from 'weifuwu'
+
+app.get('/api', (req, ctx) => {
+  console.log('Handling request', currentTraceId()) // f240a3f3-60e2-...
+})
+```
+
+**Structured logging** — `logger({ format: 'json' })` outputs JSON to stderr with `traceId`, `timestamp`, `elapsed_ms`:
+
+```json
+{"level":"info","message":"request","method":"GET","path":"/api/users","status":200,"elapsed_ms":42,"traceId":"f240a3f3-...","timestamp":"2025-01-15T10:30:00.000Z"}
+```
+
+Default format is `'short'` (human-readable). `'combined'` includes query strings.
+
+---
+
+## AI Observability
+
+Agent runs are **automatically logged** to `_agent_runs`. Dashboard endpoints provide analytics:
+
+```
+GET /agents/:id/runs?days=7       → [{ input, output, tokens_in, tokens_out, elapsed_ms, status, trace_id, ... }]
+GET /agents/:id/runs/summary?days=7 → { total, success, error, success_rate, tokens_in, tokens_out, avg_elapsed_ms, p95_elapsed_ms }
+GET /opencode/sessions/:id/usage    → { message_count, tokens_in, tokens_out, tokens_total }
+```
+
+Non-streaming runs log full token data; streaming runs log `status: 'stream'`.
+
+---
+
+## Agent ↔ Messager Streaming
+
+Agent replies in messager channels now stream **token-by-token** via WebSocket:
+
+```ts
+// Backend — automatic when agents are attached to messager
+const msg = messager({ pg, agents: agent({ pg, model }) })
+app.ws('/ws', msg.wsHandler())
+// Agent replies stream to: hub.broadcast({ type: 'agent_stream', data: { token, full } })
+```
+
+```tsx
+// Frontend — React hook
+import { useAgentStream } from 'weifuwu/react'
+
+const { getAgentText, isAgentStreaming, stream } = useAgentStream({
+  wsPath: '/ws',
+  channelId: 1,
+})
+```
+
+Multi-round conversation context: the last 10 channel messages are automatically injected into agent calls.
+
+---
+
+## Test Utilities
+
+Chainable test helper for HTTP-level testing without starting a server:
+
+```ts
+import { testApp } from 'weifuwu'
+
+const app = testApp()
+app.use(postgres({ connection: TEST_DB }))
+app.get('/users/:id', (req, ctx) => Response.json({ id: ctx.params.id, user: ctx.user }))
+
+const res = await app
+  .getReq('/users/42?name=Alice')
+  .withUser({ id: 1 })
+  .header('X-Custom', 'val')
+  .body({ data: 'test' })
+  .send()
+
+assert.equal(res.status, 200)
+assert.deepEqual(await res.json(), { id: '42', user: { id: 1 } })
+```
+
+| Method | Description |
+|--------|-------------|
+| `app.getReq(path)` `postReq` `putReq` `patchReq` `deleteReq` | Start building a request |
+| `.withUser(u)` `.withTenant(t)` `.with(ctx)` | Simulate middleware injection |
+| `.header(k,v)` `.body(data)` `.rawBody(str)` | Set request properties |
+| `.send()` → `TestResponse` | Execute and get `{ status, headers, json(), text() }` |
+
+---
+
 ## Module Reference
 
 ### agent [β]
@@ -398,6 +538,29 @@ Restart=always
 
 
 
+### graphql [β]
+
+```ts
+const handler: GraphQLHandler = () => ({
+  schema: `type Query { hello: String }`,
+  resolvers: { Query: { hello: () => 'world' } },
+  graphiql: true,         // GET / returns GraphiQL IDE
+  maxDepth: 10,            // max query nesting (default 10, 0 = disable)
+  timeout: 30_000,         // execution timeout in ms
+})
+app.use('/graphql', graphql(handler))
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `schema` | `string \| GraphQLSchema` | — | SDL string or pre-built schema |
+| `resolvers` | `object` | — | Resolver map |
+| `rootValue` | `any` | — | Root value for queries |
+| `context` | `(req, ctx) => object` | — | Per-request context factory |
+| `graphiql` | `boolean` | `false` | Serve GraphiQL IDE at GET / |
+| `maxDepth` | `number` | `10` | Max query nesting depth |
+| `timeout` | `number` | `30_000` | Execution timeout (ms) |
+
 ### health [β]
 
 ```ts
@@ -584,52 +747,70 @@ app.use(pg)                    // injects ctx.sql
 | `ssl` | `boolean\|object` | — | SSL options |
 | `idle_timeout` | `number` | `30` | Idle timeout (seconds) |
 | `connect_timeout` | `number` | `30` | Connection timeout |
+| `statementTimeout` | `number` | `30_000` | Per-statement timeout (ms, 0 = disable) |
+| `onQuery` | `(query, ms, rows) => void` | — | Query logging callback |
 
 ```ts
 // Raw SQL via tagged template
 await pg.sql`SELECT * FROM users WHERE email = ${email}`
 
-// Type-safe DDL
-import { pgTable, serial, text, boolean, timestamps } from 'weifuwu'
+// Define a table — one API, sql pre-bound
+import { serial, text, boolean, timestamps } from 'weifuwu'
 
-const users = pgTable('_users', {
+const users = pg.table('_users', {
   id: serial('id').primaryKey(),
   name: text('name').notNull(),
   email: text('email').unique().notNull(),
   active: boolean('active').default(true),
   ...timestamps(),
 })
-await users.create(pg.sql)
-await users.createIndex(pg.sql, 'email')
-
-// BoundTable — sql bound once, no need to pass sql to every call
-const t = pg.table('_users', { id: serial('id'), name: text('name'), email: text('email'), ...timestamps() })
-await t.insert({ name: 'Alice' })
-// vs unbound Table — sql passed as first argument each time
-// const t = pgTable('_users', { ... })
-// await t.insert(pg.sql, { name: 'Alice' })
-const { count, data } = await t.readMany({ role: 'admin' }, { orderBy: { name: 'asc' }, limit: 10 })
-await t.upsert({ email: 'alice@test.com' }, 'email')
-
-// Transactions
+await users.create()           // DDL — no need to pass sql
+await users.createIndex('email')
+
+// CRUD — sql already bound
+await users.insert({ name: 'Alice' })
+const { count, data } = await users.readMany({ role: 'admin' }, { orderBy: { name: 'asc' }, limit: 10 })
+await users.upsert({ email: 'alice@test.com' }, 'email')
+
+// Reuse schema without redefining fields
+import { pgTable } from 'weifuwu'
+const usersSchema = pgTable('_users', { id: serial('id'), name: text('name') })  // define once
+const users = pg.table(usersSchema)  // bind — no field duplication
+
+// Transactions — with auto-retry on deadlock/serialization failure
 await pg.transaction(async (sql) => {
-  const users = pg.table('_users', {}).withSql(sql)
-  return users.insert({ name: 'Bob' })
-})
+  const txUsers = users.withSql(sql)
+  return txUsers.insert({ name: 'Bob' })
+}, { maxRetries: 3 })
 
 // Soft delete — automatic if deleted_at column exists
-await t.delete(1)       // SET deleted_at = NOW()
-await t.hardDelete(1)   // DELETE FROM
-await t.readMany()      // WHERE deleted_at IS NULL (use withDeleted: true to include)
+await users.delete(1)       // SET deleted_at = NOW()
+await users.hardDelete(1)   // DELETE FROM
+await users.read(1)         // auto-filters deleted_at IS NULL (use withDeleted: true to include)
 
 // JSONB queries
 const logs = pg.table('logs', { meta: jsonb<{ service: string }>('meta') })
 await logs.readMany(contains('meta', { service: 'auth' }))
 
+// Connection pool visibility
+console.log(pg.poolStats())  // { active: 3, idle: 7, waiting: 0, max: 10 }
+
+// Migration tracking
+await pg.migrate()           // creates _weifuwu_migrations
+await pg.markMigrated('myModule')  // idempotent
+const done = await pg.isMigrated('myModule')
+
 // Partitioned tables
 await logs.create({ partitionBy: partitionBy('range', 'created_at') })
 ```
 
+**When to use pgTable vs pg.table:**
+| API | Use when |
+|-----|---------|
+| `pg.table('t', cols)` | You have `pg` available (factory, handler, migrate) |
+| `pg.table(schema)` | Reusing a schema without duplicating field definitions |
+| `pgTable('t', cols)` | No `pg` reference (utility modules, standalone schema files) |
+
 | Column builder | Type | Notes |
 |---------------|------|-------|
 | `serial(name)` | `number` | Auto-increment |
@@ -644,27 +825,27 @@ await logs.create({ partitionBy: partitionBy('range', 'created_at') })
 
 **Column modifiers:** `.primaryKey()`, `.notNull()`, `.nullable()`, `.default(val)`, `.unique()`, `.references(table, column?, onDelete?)`.
 
-**BoundTable CRUD methods:**
+**CRUD methods:**
 
 | Method | Description |
 |--------|-------------|
 | `insert(data)` | INSERT + RETURNING \*, returns the inserted row |
 | `insertMany(data)` | Bulk INSERT + RETURNING \*, returns rows |
-| `read(id, opts?)` | SELECT by primary key, returns row or undefined |
+| `read(id, opts?)` | SELECT by detected primary key + auto soft-delete filter |
 | `readMany(where?, opts?)` | Filtered query with `{ count, data }` — auto-filters soft-deleted |
-| `update(id, data)` | UPDATE by id + RETURNING \*, returns updated row |
+| `update(id, data)` | UPDATE by primary key + RETURNING \*, returns updated row |
 | `updateMany(where, data)` | Bulk UPDATE, returns affected row count |
 | `delete(id)` | Soft delete if `deleted_at` exists, else hard delete |
 | `hardDelete(id)` | Always DELETE FROM |
 | `deleteMany(where)` | Soft bulk delete if `deleted_at` exists |
 | `hardDeleteMany(where)` | Always DELETE FROM |
 | `upsert(data, conflict)` | INSERT ON CONFLICT DO UPDATE, returns row |
-| `count(where?)` | SELECT COUNT(\*) |
+| `count(where?)` | SELECT COUNT(\*) — auto-filters soft-deleted |
 | `create(opts?)` | CREATE TABLE IF NOT EXISTS |
 | `drop(opts?)` | DROP TABLE IF EXISTS |
 | `createIndex(columns, opts?)` | CREATE INDEX |
 | `createUniqueIndex(columns)` | CREATE UNIQUE INDEX |
-| `withSql(sql)` | Returns a new BoundTable bound to a different sql (for transactions) |
+| `withSql(sql)` | Returns copy bound to a different sql (for transactions) |
 
 **Where helpers** — composable query conditions:
 
@@ -1120,7 +1301,8 @@ Every public symbol can be imported from `'weifuwu'`:
 ```ts
 serve, createTestServer, Router, ssr,
 Context, Handler, Middleware, ErrorHandler, ServeOptions, Server,
-loadEnv
+loadEnv, testApp, TestApp, TestRequest, TestResponse,
+currentTraceId, currentTrace, runWithTrace, traceElapsed, TraceContext,
 ```
 
 ### Middleware modules
@@ -1136,6 +1318,7 @@ preferences, serveStatic
 postgres, PostgresOptions, PostgresClient,
 redis, RedisOptions, RedisClient,
 queue, QueueOptions, QueueJob, Queue,
+PostgresInjected, RedisInjected, QueueInjected,
 // Schema helpers — importable alongside postgres:
 pgTable, SQL, sql,
 ColumnBuilder, serial, uuid, text, integer, boolean, boolean_, timestamptz, jsonb, textArray, vector,
@@ -1151,8 +1334,10 @@ TsxContext, useLoaderData,
 useWebsocket, useAction, useFetch, useQueryState, createStore,
 Link, useNavigate, useNavigating, addInterceptor,
 useLocale, useTheme, applyTheme, useFlashMessage,
+useAgentStream,
 Head
 ```
+export type { UseAgentStreamOptions, UseAgentStreamReturn, AgentStreamState } from 'weifuwu/react'
 
 ### AI SDK (re-exported from `ai`)
 
@@ -1169,8 +1354,12 @@ preferences, health, analytics, seo, seoMiddleware, seoTags,
 user, mailer, graphql, aiStream, runWorkflow,
 logdb, messager, agent, iii, createWorker, registerWorker,
 opencode, deploy, defineConfig,
+testApp, TestApp, TestRequest, TestResponse,
 getCookies, setCookie, deleteCookie,
-createSSEStream, formatSSE, formatSSEData
+createSSEStream, formatSSE, formatSSEData,
+currentTraceId, currentTrace, runWithTrace, traceElapsed,
+createHub, Hub, HubOptions,
+DEFAULT_MAX_BODY, MIGRATIONS_TABLE,
 ```
 
 ---

package/cli/template/index.ts

@@ -3,6 +3,4 @@ import { app } from './app.ts'
 
 loadEnv()
 const port = Number(process.env.PORT) || 3000
-const server = serve(app.handler(), { port, websocket: app.websocketHandler() })
-await server.ready
-console.log(`Listening on http://localhost:${server.port}`)
+serve(app.handler(), { port, websocket: app.websocketHandler() })