weifuwu 0.31.1 → 0.32.0

package/README.md

@@ -21,7 +21,7 @@ serve(app, { port: 3000 })
 | Export | Description |
 |---|---|
 | `serve(app, opts?)` | Start HTTP server. Returns `Server` with `port`, `hostname`, `ready`, `close()`. |
-| `Router` | Trie-based HTTP router with WebSocket support. |
+| `Router` | Trie-based HTTP router with WebSocket support and `plugin()` method. |
 | `HttpError` | `new HttpError(message, status)`. Throw to return that status code. |
 | `DEFAULT_MAX_BODY` | `10 * 1024 * 1024` (10MB). |
 
@@ -42,6 +42,7 @@ app.ws(path, ...middlewares, handler)
 // Middleware & mounting
 app.use(middleware)           // global middleware
 app.mount(prefix, router)     // sub-router at prefix
+app.plugin(fn)                // extension: (app) => { app.get(), app.use(), ... }
 app.onError(handler)          // error handler: (error, req, ctx) => Response
 app.routes()                  // debug: list all registered routes
 
@@ -63,7 +64,8 @@ app.get('/users/:id', (req, ctx) => {
 | `logger(opts?)` | Request logging. `format: 'short' | 'combined' | 'json'`. |
 | `upload(opts?)` | Multipart file upload via `req.formData()`. Injects `ctx.parsed`. |
 | `serveStatic(root, opts?)` | Static file handler. `cacheControl`, `index`. |
-| `trace(opts?)` | Injects `ctx.trace = { requestId, traceId, elapsed(), startTime }`. |
+| `sandbox(opts?)` | Filesystem isolation for agent operations. `baseDir`, `timeout`, `isolateBy`. |
+| `auth(opts?)` | Authentication: JWT, session cookies, API keys. Injects `ctx.user`. |
 
 ### Tracing
 
@@ -178,111 +180,241 @@ npm install react react-dom
 ```
 
 ```ts
-import { react, Link, useServerData, ErrorBoundary } from 'weifuwu'
-import { createElement as h } from 'react'
+// server.ts — the only file you need
+import { serve, Router } from 'weifuwu'
+import { react } from 'weifuwu/react'
 
-// ── Server ──────────────────────────────────────────────
+const app = new Router()
+  .use(trace())
+  .use(logger())
+  .plugin(react({
+    pages: {
+      '/':          './pages/Home.tsx',
+      '/users':     './pages/Users.tsx',
+      '/users/:id': './pages/UserDetail.tsx',
+    },
+    layout:   './layouts/Root.tsx',
+    notFound: './pages/NotFound.tsx',
+    tailwind: { entry: './styles/input.css' },
+  }))
 
-app.use(react({
-  layout: ({ children }) =>
-    h('html', null,
-      h('head', null, h('title', null, 'My App')),
-      h('body', null, h('div', { id: 'root' }, children)),
-    ),
-}))
+app.get('/api/hello', () => Response.json({ message: 'hi' }))
+serve(app, { port: 3000 })
+```
+
+**One `react()` call handles:** SSR rendering, routing, data loading, Tailwind CSS, client bundle auto-generation, and error pages. No `client.ts`, `routes.ts`, or manual middleware setup needed.
+
+#### Page components
+
+```tsx
+// pages/UserDetail.tsx
+import type { Context } from 'weifuwu'
+import { HttpError } from 'weifuwu'
+import { useServerData } from 'weifuwu/react'
 
-// Render React components to HTML
-app.get('/', (_req, ctx) =>
-  ctx.render(h('h1', null, 'Hello SSR'), {
-    head: { title: 'Home' },
-    data: { greeting: 'Hello' },
-  })
-)
-
-// Streaming SSR
-app.get('/dashboard', (_req, ctx) =>
-  ctx.renderStream(h(Dashboard))
-)
-
-// Layout nesting via mount
-const admin = new Router()
-admin.use(react({ layout: AdminLayout }))
-admin.get('/dashboard', (_req, ctx) => ctx.render(h(AdminDashboard)))
-app.mount('/admin', admin)
-
-// ── Shared components ──────────────────────────────────
-
-// Use the same component on server and client
-function Page() {
-  const { greeting } = useServerData<{ greeting: string }>()
-  return h('h1', null, greeting)
+export async function loader(ctx: Context) {
+  const user = await db.find(ctx.params.id)
+  if (!user) throw new HttpError('Not found', 404)
+  return { user }
 }
 
-// Link works on both sides: <a> on server, SPA <a> on client
-function Nav() {
-  return h('nav', null,
-    h(Link, { href: '/' }, 'Home'),
-    h(Link, { href: '/users' }, 'Users'),
+export default function UserDetailPage() {
+  const { user } = useServerData<{ user: User }>()
+  return (
+    <div>
+      <title>{`${user.name} — My App`}</title>
+      <h1>{user.name}</h1>
+      <p>{user.email}</p>
+    </div>
   )
 }
+```
+
+- `export async function loader(ctx)` — runs on the server, returns data for `useServerData()`
+- `throw new HttpError('Not found', 404)` — renders the NotFound page with correct status
+- `<title>` auto-hoists to `<head>` via React 19
+- `export default` is auto-detected; named exports work too
 
-// ErrorBoundary catches client-side render errors
-function SafeUserProfile() {
-  return h(ErrorBoundary, { fallback: h('div', null, 'Error') },
-    h(UserProfile),
+#### Layout with shared data
+
+```tsx
+// layouts/Root.tsx
+export async function loader(ctx: Context) {
+  return { currentUser: await getCurrentUser(ctx) }
+}
+
+export function Root({ children }: { children: ReactNode }) {
+  const { currentUser } = useServerData()
+  return (
+    <>
+      <nav>
+        <a href="/">Home</a>
+        <a href="/users">Users</a>
+        <span>{currentUser?.name}</span>
+      </nav>
+      <main>{children}</main>
+    </>
   )
 }
+```
 
-// ── Client (SPA navigation) ────────────────────────────
+Layout `loader` data merges with page data. Page loader overrides same keys.
 
-// client.ts — bundled separately with esbuild
-import { hydrate, createClientRouter, defineRoute } from 'weifuwu/react/client'
+#### Data flow
 
-const userRoute = defineRoute({
-  path: '/users/:id',
-  component: UserPage,
-  loader: (params) => fetch(`/users/${params.id}?_data`).then(r => r.json()),
-})
+```
+layout loader  ──┐
+                  ├──→  merge → useServerData()  ──→  Layout + Page
+page loader   ───┘
+```
+
+#### Client-side SPA
+
+Every page is automatically code-split into a separate chunk. On first visit the server renders HTML and the client hydrates. Subsequent navigations intercept `<a>` clicks, `import()` the page chunk, and fetch fresh server data — all automatic, zero config.
 
-const router = createClientRouter([
-  { path: '/', component: HomePage },
-  userRoute,
-])
+#### Streaming SSR
 
-hydrate(router.App)
+```tsx
+import { Suspense, use } from 'react'
+
+export default function StreamingPage() {
+  return (
+    <div>
+      <h1>Instant shell</h1>
+      <Suspense fallback={<Spinner />}>
+        <SlowData promise={fetchSlowData()} />
+      </Suspense>
+    </div>
+  )
+}
 ```
 
-**Key concepts:**
+`<Suspense>` boundaries stream to the browser as data resolves.
 
 | Feature | Description |
 |---|---|
-| `ctx.render(el, opts)` | Render React to HTML. Auto-detects `?_data` → returns JSON. |
-| `ctx.renderStream(el)` | Streaming SSR via `renderToReadableStream`. |
-| `useServerData<T>()` | Access data on both server (via `ctx.render({ data })`) and client (via `loader`). |
-| `Link` | Shared component — `<a>` on server, SPA `<a>` on client. |
-| `Form` | Shared — `<form>` on server, `fetch` + revalidate on client. |
-| `ErrorBoundary` | Catches render errors on client (SSR uses `onError`). |
-| `useNavigation()` | `{ state: 'idle' \| 'loading' }` for progress indicators. |
-| `useParams()` / `useNavigate()` / `useRevalidate()` | Router hooks. |
-| `defineRoute()` | Type-safe route config — captures loader return type. |
-| `createClientRouter()` | Client-side SPA router with loader-based data fetching. |
-| `hydrate(App)` | Hydrate server-rendered HTML on the client. |
-| `head: { title, meta }` | Inject dynamic `<title>` and `<meta>` tags. |
+| `react({ pages, layout, notFound, tailwind })` | One call: SSR + routing + client bundle + error handling |
+| `export async function loader(ctx)` | Server-side data loading, auto-detected by the framework |
+| `useServerData<T>()` | Type-safe access to loader data in any component |
+| `Link` | `<a>` that does SPA navigation on the client |
+| `ErrorBoundary` | Catches render errors on server and client |
+| `<title>`, `<meta>` | Auto-hoisted to `<head>` via React 19 |
+| `<Suspense>` | Streaming SSR, works out of the box |
+| `client: false` | Disable client JS for static SSR only |
 
 **Import paths:**
 
 ```ts
 // Server-side
-import { react, Link, Form, ErrorBoundary, useServerData } from 'weifuwu'
+import { react, Link, ErrorBoundary, useServerData } from 'weifuwu'
+
+// Client-side (for custom advanced setups)
+import { createBrowserRouter, hydrate, navigate } from 'weifuwu/react/client'
+```
+
+See [examples/react-ssr/](examples/react-ssr/) for the full demo.
 
-// Client-side (for browser bundles)
-import { hydrate, createClientRouter, defineRoute, Link } from 'weifuwu/react/client'
+### AI Agent
 
-// Shared primitives (safe for both, pure React — no react-dom import)
-import { Link, Form, useServerData, useParams, useNavigation } from 'weifuwu/react/navigation'
+> Requires `ai` (Vercel AI SDK). Install with a model provider:
+> ```bash
+> npm install ai @ai-sdk/openai
+> ```
+
+```ts
+import { agent } from 'weifuwu'
+import { openai } from '@ai-sdk/openai'
+import { tool } from 'ai'
+import { z } from 'zod'
+
+app.use(agent({
+  model: openai('gpt-4o'),
+  system: 'You are a helpful assistant.',
+  knowledge: {
+    // RAG — search a knowledge base before each response
+    search: async (query, ctx) => {
+      const { embeddings } = await embedModel.doEmbed({ values: [query] })
+      return ctx.sql`
+        SELECT content, 1 - (embedding <=> ${embeddings[0]}::vector) AS score
+        FROM docs ORDER BY embedding <=> ${embeddings[0]}::vector LIMIT 3
+      `
+    },
+  },
+  tools: {
+    getWeather: tool({
+      description: 'Get weather for a city',
+      parameters: z.object({ city: z.string() }),
+      execute: async ({ city }) => ({ temp: 22, unit: 'C' }),
+    }),
+  },
+  maxSteps: 5,
+}))
+
+app.post('/api/chat', async (req, ctx) => {
+  const { messages } = await req.json()
+  return ctx.agent.chatStreamResponse({ messages })
+})
 ```
 
-See [examples/react-ssr/](examples/react-ssr/) for a complete demo.
+**`agent()` handles:** multi-turn conversations, automatic tool-calling loops (maxSteps), knowledge retrieval (RAG) injected into the system prompt, and SSE streaming compatible with `useChat` from `@ai-sdk/react`.
+
+| Feature | Description |
+|---|---|
+| `ctx.agent.chat(prompt, opts?)` | Non-streaming chat with tool calling and RAG |
+| `ctx.agent.chatStreamResponse({ messages })` | SSE streaming response (useChat-compatible) |
+| `knowledge.search` | User-defined RAG callback — query any data source via `ctx` |
+| `tools` | Tool definitions (from `ai` package). Executed in automatic loops |
+| `agents` | Named sub-agents with different models/tools |
+| `sandbox: true` | Auto-integrate with `ctx.sandbox` for file operations |
+| `store` | Session persistence (save/load conversation history) |
+
+### Auth
+
+```ts
+import { auth } from 'weifuwu'
+
+// JWT
+app.use(auth({ jwt: { secret: process.env.JWT_SECRET } }))
+
+// Session cookie
+app.use(auth({
+  session: {
+    secret: '...',
+    loadUser: async (data) => db.findUser(data.userId),
+  },
+}))
+
+// API key
+app.use(auth({ apiKey: { validate: async (key) => db.findByApiKey(key) } }))
+
+// ctx.user is now available
+app.get('/me', (req, ctx) => {
+  if (!ctx.user) return new Response('Unauthorized', { status: 401 })
+  return Response.json(ctx.user)
+})
+```
+
+Supports JWT (HS256 via cookie or Authorization header), signed session cookies with `loadUser` callback, and API key validation. All are optional — requests proceed without a user identity unless handlers enforce it.
+
+### Sandbox
+
+```ts
+import { sandbox } from 'weifuwu'
+
+app.use(sandbox({
+  baseDir: '/tmp/workspaces',
+  timeout: 30000,
+  isolateBy: 'user',  // one directory per ctx.user.id
+}))
+
+// ctx.sandbox provides isolated file + exec operations
+await ctx.sandbox.writeFile('hello.txt', 'world')
+const content = await ctx.sandbox.readFile('hello.txt')
+const { stdout } = await ctx.sandbox.exec('ls -la')
+await ctx.sandbox.destroy()  // clean up workspace
+```
+
+All file paths are validated — escapes (`../`) are rejected. `exec()` enforces timeout and sets `HOME` to the workspace directory. When `isolateBy: 'user'` is set, each user gets their own directory under `baseDir`.
 
 ### Types
 
@@ -339,50 +471,35 @@ app.onError((err, req, ctx) => {
 ## Complete example
 
 ```ts
-import { serve, Router, cors, helmet, compress, logger, trace, rateLimit, postgres, redis, queue, HttpError } from 'weifuwu'
+import { serve, Router, cors, helmet, compress, logger, trace, rateLimit, postgres, redis, auth, sandbox, HttpError } from 'weifuwu'
+import { agent } from 'weifuwu/agent'
+import { react } from 'weifuwu/react'
+import { openai } from '@ai-sdk/openai'
 
 const app = new Router()
-
-// Global middleware
-app.use(trace())
-app.use(logger())
-app.use(cors())
-app.use(helmet())
-app.use(compress())
-app.use(rateLimit({ windowMs: 60_000, max: 100 }))
-
-// Database
-const sql = postgres()
-app.use(sql)
-
-// Routes
-app.get('/api/users', async (req, ctx) => {
-  const users = await ctx.sql`SELECT id, name FROM users ORDER BY id`
-  return Response.json(users)
-})
-
-app.post('/api/users', async (req, ctx) => {
-  const { name, email } = await req.json()
-  const [user] = await ctx.sql`INSERT INTO users (name,email) VALUES (${name},${email}) RETURNING *`
-  return Response.json(user, { status: 201 })
-})
-
-app.get('/api/users/:id', async (req, ctx) => {
-  const [user] = await ctx.sql`SELECT * FROM users WHERE id = ${ctx.params.id}`
-  if (!user) throw new HttpError('Not found', 404)
-  return Response.json(user)
-})
-
-// WebSocket
-app.ws('/chat', {
-  open(ws, ctx) { ctx.ws.join('lobby') },
-  message(ws, ctx, data) { ctx.ws.sendRoom('lobby', { text: data.toString() }) },
-})
-
-// Error handling
-app.onError((err) => {
-  if (err instanceof HttpError) return Response.json({ error: err.message }, { status: err.status })
-  return Response.json({ error: 'Internal error' }, { status: 500 })
+  .use(trace())
+  .use(logger())
+  .use(cors())
+  .use(helmet())
+  .use(compress())
+  .use(postgres())
+  .use(redis())
+  .use(auth({ jwt: { secret: process.env.JWT_SECRET! } }))
+  .use(sandbox({ isolateBy: 'user' }))
+  .use(agent({
+    model: openai('gpt-4o'),
+    system: 'You are a helpful assistant.',
+    knowledge: {
+      search: async (q, ctx) => ctx.sql`...`,
+    },
+    sandbox: true,
+  }))
+  .plugin(react({ pages: { '/': './Chat.tsx' }, layout: './Layout.tsx', tailwind: {} }))
+
+app.post('/api/chat', async (req, ctx) => {
+  if (!ctx.user) return new Response('Unauthorized', { status: 401 })
+  const { messages } = await req.json()
+  return ctx.agent.chatStreamResponse({ messages })
 })
 
 serve(app, { port: 3000 })
@@ -403,6 +520,7 @@ weifuwu/
 │   ├── types.ts
 │   ├── core/               ← serve, router, ws, trace, logger
 │   ├── middleware/          ← cors, helmet, compress, rate-limit, static, upload
+│   ├── ai/                  ← AI + agent middleware
 │   ├── postgres/
 │   ├── redis/
 │   ├── react/              ← react SSR (render, navigation, client)

package/dist/ai/agent.d.ts

@@ -0,0 +1,127 @@
+import type { Middleware, Context } from '../types.ts';
+import type { AiOptions } from '../ai/types.ts';
+declare module '../types.ts' {
+    interface Context {
+        /**
+         * AI agent — LLM integration with session management, tool calling,
+         * knowledge retrieval, and streaming.
+         * Injected by the `agent()` middleware.
+         */
+        agent: Agent;
+    }
+}
+export interface Agent {
+    /**
+     * Chat with the agent (non-streaming). Returns the final response
+     * after tool calls and knowledge retrieval.
+     */
+    chat(prompt: string, opts?: AgentChatOptions): Promise<AgentChatResult>;
+    /**
+     * Stream the agent's response as an SSE Response.
+     * Compatible with `useChat` from @ai-sdk/react.
+     */
+    chatStreamResponse(opts: AgentStreamOptions): Response;
+    /** The underlying language model. */
+    model: unknown;
+    /** Default system prompt. */
+    system: string | undefined;
+}
+export interface AgentChatOptions {
+    /** Override system prompt for this call. */
+    system?: string;
+    /** Chat history messages (from useChat). */
+    messages?: Array<{
+        role: string;
+        content: string;
+        [key: string]: unknown;
+    }>;
+    /** Override temperature. */
+    temperature?: number;
+    /** Override max tokens. */
+    maxTokens?: number;
+    /** Override max steps. */
+    maxSteps?: number;
+}
+export interface AgentStreamOptions {
+    /** User prompt or full message list. */
+    messages: Array<{
+        role: string;
+        content: string;
+        [key: string]: unknown;
+    }>;
+    /** Override system prompt. */
+    system?: string;
+}
+export type AgentChatResult = Record<string, any>;
+export interface AgentOptions extends AiOptions {
+    /**
+     * Knowledge base for RAG. Called before every chat to inject context.
+     */
+    knowledge?: {
+        /**
+         * Search for relevant documents given a user query.
+         * Results are injected into the system prompt.
+         */
+        search: (query: string, ctx: Context) => Promise<Array<{
+            content: string;
+            score?: number;
+        }>>;
+        /** Maximum results to inject (default: 3). */
+        topK?: number;
+        /** Minimum relevance score (default: 0). */
+        minScore?: number;
+    };
+    /**
+     * Named sub-agents with their own model, system prompt, and tools.
+     * Access via ctx.agent.agents[name].
+     */
+    agents?: Record<string, {
+        model?: unknown;
+        system?: string;
+        tools?: Record<string, unknown>;
+    }>;
+    /**
+     * Enable sandbox integration. When true and ctx.sandbox is available,
+     * the agent automatically uses it for file operations.
+     */
+    sandbox?: boolean;
+    /**
+     * Store for session persistence. Save/load conversation history.
+     */
+    store?: {
+        save: (sessionId: string, messages: unknown[]) => Promise<void>;
+        load: (sessionId: string) => Promise<unknown[]>;
+    };
+}
+/**
+ * AI Agent middleware — injects `ctx.agent` for LLM-powered conversations.
+ *
+ * Built on the Vercel AI SDK. Supports:
+ * - Multi-turn conversations with session history
+ * - Tool calling with automatic loops (maxSteps)
+ * - Knowledge retrieval (RAG) via `knowledge.search`
+ * - Streaming SSE responses compatible with `useChat` from @ai-sdk/react
+ * - Named sub-agents for role-based delegation
+ * - Sandbox integration
+ *
+ * @example
+ * ```ts
+ * import { agent } from 'weifuwu'
+ * import { openai } from '@ai-sdk/openai'
+ *
+ * app.use(agent({
+ *   model: openai('gpt-4o'),
+ *   system: 'You are a helpful assistant.',
+ *   knowledge: {
+ *     search: async (query, ctx) => ctx.sql`...pgvector...`,
+ *   },
+ *   tools: { getWeather: tool({...}) },
+ * }))
+ *
+ * app.post('/api/chat', async (req, ctx) => {
+ *   const { messages } = await req.json()
+ *   return ctx.agent.chatStreamResponse({ messages })
+ * })
+ * ```
+ */
+export declare function agent(opts: AgentOptions): Middleware;

package/dist/ai/index.d.ts

@@ -0,0 +1,26 @@
+import type { Middleware } from '../types.ts';
+import type { AiOptions } from './types.ts';
+export type { AiOptions, Ai } from './types.ts';
+/**
+ * AI middleware — injects `ctx.ai` for LLM integration via the Vercel AI SDK.
+ *
+ * Requires a language model provider (e.g. `@ai-sdk/openai`, `@ai-sdk/anthropic`).
+ *
+ * @example
+ * ```ts
+ * import { ai } from 'weifuwu'
+ * import { openai } from '@ai-sdk/openai'
+ *
+ * app.use(ai({
+ *   model: openai('gpt-4o'),
+ *   system: 'You are a helpful assistant.',
+ * }))
+ *
+ * app.post('/api/chat', async (req, ctx) => {
+ *   const { prompt } = await req.json()
+ *   const result = await ctx.ai.generateText({ prompt })
+ *   return Response.json({ text: result.text })
+ * })
+ * ```
+ */
+export declare function ai(opts: AiOptions): Middleware;

package/dist/ai/types.d.ts

@@ -0,0 +1,59 @@
+declare module '../types.ts' {
+    interface Context {
+        /** AI / LLM integration. Injected by the `ai()` middleware. */
+        ai: Ai;
+    }
+}
+export interface Ai {
+    /**
+     * Generate text (non-streaming). See `generateText` from the `ai` package.
+     *
+     * @example
+     * const { text, toolCalls, steps } = await ctx.ai.generateText({
+     *   prompt: 'What is the weather?',
+     * })
+     */
+    generateText(opts: GenerateTextParams): Promise<AiGenerateTextResult>;
+    /** The language model instance. */
+    model: unknown;
+    /** Default system prompt. */
+    system: string | undefined;
+}
+export type AiGenerateTextResult = Awaited<ReturnType<typeof import('ai').generateText<any, any, any>>>;
+export interface AiOptions {
+    /**
+     * Language model instance (from @ai-sdk/openai, @ai-sdk/anthropic, etc.).
+     *
+     * @example
+     * import { openai } from '@ai-sdk/openai'
+     * ai({ model: openai('gpt-4o') })
+     */
+    model: unknown;
+    /** System prompt added to every request. */
+    system?: string;
+    /** Tools available for tool calling. */
+    tools?: any;
+    /** Maximum agent steps for tool-calling loops (default: 1). */
+    maxSteps?: number;
+    /** Default temperature (0–2). */
+    temperature?: number;
+    /** Default max output tokens. */
+    maxTokens?: number;
+}
+export interface GenerateTextParams {
+    /** User prompt. */
+    prompt: string;
+    /** System prompt override. */
+    system?: string;
+    /** Chat history messages. */
+    messages?: Array<{
+        role: string;
+        content: string;
+    } & Record<string, any>>;
+    /** Override temperature. */
+    temperature?: number;
+    /** Override max tokens. */
+    maxTokens?: number;
+    /** Override max steps. */
+    maxSteps?: number;
+}

package/dist/core/router.d.ts

@@ -25,6 +25,17 @@ export declare class Router<T extends Context = Context> {
     private get hub();
     wsHub(hub: Hub): this;
     use(mw: Middleware<Context, Context>): Router<T>;
+    /**
+     * Install a plugin — a function that configures the Router with
+     * routes, middleware, and error handlers. Use when `.use()` isn't
+     * enough because you need to call `app.get()`, `app.onError()`, etc.
+     *
+     * @example
+     * ```ts
+     * app.plugin(app => createReactApp(app, { pages: {...}, layout: '...', tailwind: {...} }))
+     * ```
+     */
+    plugin(fn: (app: this) => void): this;
     mount(path: string, router: Router<Context>): Router<T>;
     onError(handler: ErrorHandler<T>): Router<T>;
     get(path: string, ...rest: [...Middleware[], Handler | Router<Context>]): Router<T>;