raffel 1.0.6 → 1.0.7

package/dist/mcp/docs/patterns.js

@@ -42,18 +42,27 @@ export const patterns = [
 
 const server = createServer({ port: 3000 })
   .procedure('users.list')
-    .handler(async (input, ctx) => {
-      return await db.users.findMany()
+    .handler(async (_input, ctx) => {
+      const services = ctx.services as {
+        users: { list(): Promise<unknown[]> }
+      }
+      return services.users.list()
     })
 
   .procedure('users.get')
     .handler(async ({ id }, ctx) => {
-      return await db.users.findUnique({ where: { id } })
+      const services = ctx.services as {
+        users: { get(id: string): Promise<unknown> }
+      }
+      return services.users.get(id)
     })
 
   .procedure('users.create')
     .handler(async (input, ctx) => {
-      return await db.users.create({ data: input })
+      const services = ctx.services as {
+        users: { create(data: unknown): Promise<unknown> }
+      }
+      return services.users.create(input)
     })
 
 await server.start()`,
@@ -81,7 +90,10 @@ const server = createServer({ port: 3000 })
       email: z.string()
     }))
     .handler(async (input, ctx) => {
-      return await db.users.create({ data: input })
+      const services = ctx.services as {
+        users: { create(data: unknown): Promise<unknown> }
+      }
+      return services.users.create(input)
     })
 
 await server.start()`,
@@ -381,7 +393,7 @@ const server = createServer()
     // === Pattern 4: Providers (Dependency Injection) ===
     {
         name: 'Providers (Dependency Injection)',
-        description: 'Providers register singleton dependencies that are initialized at server.start() and available in ctx. Use for database clients, cache connections, external APIs.',
+        description: 'Providers register singleton dependencies that are initialized at server.start(). In new code, prefer consuming them via ctx.services instead of broad top-level bags.',
         components: ['provide', 'ProviderFactory', 'onShutdown'],
         signature: `.provide('name', factoryFn, options?)
 
@@ -393,9 +405,11 @@ type ProviderFactory<T> = (deps: ResolvedProviders) => T | Promise<T>
   onShutdown?: (instance: T) => Promise<void>  // Cleanup on server.stop()
 }
 
-// Access in handlers
-ctx.db     // If registered as 'db'
-ctx.redis  // If registered as 'redis'`,
+// Preferred access in handlers
+const services = ctx.services as {
+  db: PrismaClient
+  redis: Redis
+}`,
         correctExamples: [
             {
                 title: 'Database Provider',
@@ -415,8 +429,8 @@ const server = createServer()
 
   .procedure('users.list')
     .handler(async (input, ctx) => {
-      // ctx.db is PrismaClient, fully typed!
-      return await ctx.db.users.findMany()
+      const services = ctx.services as { db: PrismaClient }
+      return await services.db.users.findMany()
     })`,
             },
             {
@@ -519,22 +533,25 @@ import { z } from 'zod'
 export const usersModule = createRouterModule()
   .procedure('list')
     .output(z.array(UserSchema))
-    .handler(async (input, ctx) => {
-      return await ctx.db.users.findMany()
+    .handler(async (_input, ctx) => {
+      const services = ctx.services as { users: { list(): Promise<unknown[]> } }
+      return services.users.list()
     })
 
   .procedure('get')
     .input(z.object({ id: z.string() }))
     .output(UserSchema)
     .handler(async ({ id }, ctx) => {
-      return await ctx.db.users.findUnique({ where: { id } })
+      const services = ctx.services as { users: { get(id: string): Promise<unknown> } }
+      return services.users.get(id)
     })
 
   .procedure('create')
     .input(CreateUserSchema)
     .output(UserSchema)
     .handler(async (input, ctx) => {
-      return await ctx.db.users.create({ data: input })
+      const services = ctx.services as { users: { create(data: unknown): Promise<unknown> } }
+      return services.users.create(input)
     })`,
             },
             {
@@ -560,10 +577,16 @@ import { createRouterModule } from 'raffel'
 
 export default createRouterModule()
   .procedure('list')
-    .handler(async (_, ctx) => ctx.db.users.findMany())
+    .handler(async (_, ctx) => {
+      const services = ctx.services as { users: { list(): Promise<unknown[]> } }
+      return services.users.list()
+    })
 
   .procedure('create')
-    .handler(async (input, ctx) => ctx.db.users.create({ data: input }))
+    .handler(async (input, ctx) => {
+      const services = ctx.services as { users: { create(data: unknown): Promise<unknown> } }
+      return services.users.create(input)
+    })
 
 // Server auto-discovers:
 // src/http/users.ts → users.list, users.create
@@ -642,7 +665,10 @@ const server = createServer()
     .output(UserOutput)
     .handler(async (input, ctx) => {
       // input is typed as { name: string, email: string, age?: number }
-      return await ctx.db.users.create({ data: input })
+      const services = ctx.services as {
+        users: { create(args: { data: unknown }): Promise<unknown> }
+      }
+      return await services.users.create({ data: input })
     })`,
             },
             {
@@ -663,7 +689,10 @@ const CreateOrderInput = yup.object({
 server.procedure('orders.create')
   .input(CreateOrderInput)
   .handler(async (input, ctx) => {
-    return await ctx.db.orders.create({ data: input })
+    const services = ctx.services as {
+      orders: { create(args: { data: unknown }): Promise<unknown> }
+    }
+    return await services.orders.create({ data: input })
   })`,
             },
             {
@@ -740,7 +769,8 @@ onError: (error, protocol, ctx) => { ... }`,
 
 server.procedure('users.get')
   .handler(async ({ id }, ctx) => {
-    const user = await ctx.db.users.findUnique({ where: { id } })
+    const services = ctx.services as { users: { get(id: string): Promise<unknown> } }
+    const user = await services.users.get(id)
 
     if (!user) {
       throw new RaffelError(
@@ -755,7 +785,13 @@ server.procedure('users.get')
 
 server.procedure('users.create')
   .handler(async (input, ctx) => {
-    const existing = await ctx.db.users.findByEmail(input.email)
+    const services = ctx.services as {
+      users: {
+        findByEmail(email: string): Promise<unknown>
+        create(data: unknown): Promise<unknown>
+      }
+    }
+    const existing = await services.users.findByEmail(input.email)
 
     if (existing) {
       throw new RaffelError(
@@ -765,7 +801,7 @@ server.procedure('users.create')
       )
     }
 
-    return await ctx.db.users.create({ data: input })
+    return await services.users.create(input)
   })`,
             },
             {
@@ -778,11 +814,14 @@ server.procedure('orders.process')
       throw Errors.unauthenticated('Login required')
     }
 
-    if (!ctx.auth?.claims?.roles?.includes('admin')) {
+    if (!ctx.auth?.roles?.includes('admin')) {
       throw Errors.permissionDenied('Admin access required')
     }
 
-    const order = await ctx.db.orders.findUnique({ where: { id: input.id } })
+    const services = ctx.services as {
+      orders: { get(id: string): Promise<unknown> }
+    }
+    const order = await services.orders.get(input.id)
     if (!order) {
       throw Errors.notFound(\`Order \${input.id} not found\`)
     }
@@ -815,7 +854,12 @@ server.procedure('orders.process')
                 code: `server.procedure('payments.charge')
   .error(async (error, ctx) => {
     // Payment-specific error handling
-    await ctx.db.payments.update({
+    const services = ctx.services as {
+      payments: {
+        update(args: { where: { id: string }, data: Record<string, unknown> }): Promise<unknown>
+      }
+    }
+    await services.payments.update({
       where: { id: ctx.paymentId },
       data: { status: 'failed', error: error.message }
     })
@@ -912,7 +956,10 @@ server.stream('data.export')
     })
 
     // Producer
-    const cursor = ctx.db.records.findMany({ cursor: true })
+    const services = ctx.services as {
+      records: { streamCursor(input: unknown): AsyncIterable<unknown> }
+    }
+    const cursor = services.records.streamCursor(input)
     for await (const record of cursor) {
       // write() returns false if buffer is full
       const ready = stream.write(record)
@@ -939,7 +986,10 @@ server.stream('data.export')
     ;(async () => {
       for await (const message of inputStream) {
         // Process and broadcast
-        const saved = await ctx.db.messages.create({ data: message })
+        const services = ctx.services as {
+          messages: { create(data: unknown): Promise<unknown> }
+        }
+        const saved = await services.messages.create(message)
         output.write({ type: 'message', data: saved })
       }
     })()
@@ -1005,7 +1055,7 @@ server.stream('data.process')
 // Emit from a procedure
 server.procedure('pages.view')
   .handler(async (input, ctx) => {
-    await ctx.emit('analytics.pageView', { page: input.path, userId: ctx.auth?.principal })
+    await ctx.emit('analytics.pageView', { page: input.path, userId: ctx.auth?.principalId })
     return { ok: true }
   })`,
             },
@@ -1050,7 +1100,10 @@ server.procedure('pages.view')
     } catch (error) {
       if (error.code === 'DEVICE_NOT_REGISTERED') {
         // Don't retry - device is invalid
-        await ctx.db.devices.delete({ where: { id: payload.deviceId } })
+        const services = ctx.services as {
+          devices: { delete(args: { where: { id: string } }): Promise<unknown> }
+        }
+        await services.devices.delete({ where: { id: payload.deviceId } })
         ack()  // Acknowledge to stop retries
       }
       // Other errors: don't ack, will retry

package/dist/mcp/docs/patterns.js.map

@@ -1 +1 @@
-{"version":3,"file":"patterns.js","sourceRoot":"","sources":["../../../src/mcp/docs/patterns.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"patterns.js","sourceRoot":"","sources":["../../../src/mcp/docs/patterns.ts"],"names":[],"mappings":"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"}

package/dist/mcp/docs/quickstart.d.ts

@@ -3,7 +3,7 @@
  *
  * Getting started with Raffel - from zero to production-ready API.
  */
-export declare const quickstartGuide = "# Raffel Quickstart\n\n## Installation\n\n```bash\npnpm add raffel\n# or\nnpm install raffel\n```\n\n## Basic Server\n\n```typescript\nimport { createServer } from 'raffel'\n\nconst server = createServer({ port: 3000 })\n  .procedure('hello')\n    .handler(async (input, ctx) => {\n      return { message: `Hello, ${input.name || 'World'}!` }\n    })\n\nawait server.start()\nconsole.log('Server running on http://localhost:3000')\n```\n\n## Core Concepts\n\n### 1. Procedures (RPC Endpoints)\n\n```typescript\n// Unary RPC: Input \u2192 Output\nserver.procedure('users.create')\n  .handler(async (input, ctx) => {\n    return await db.users.create({ data: input })\n  })\n```\n\n### 2. Input/Output Validation\n\n```typescript\nimport { z } from 'zod'\nimport { registerValidator, createZodAdapter } from 'raffel'\n\nregisterValidator(createZodAdapter(z))\n\nserver.procedure('users.create')\n  .input(z.object({\n    name: z.string().min(2),\n    email: z.string().email()\n  }))\n  .output(z.object({\n    id: z.string(),\n    name: z.string(),\n    email: z.string()\n  }))\n  .handler(async (input, ctx) => {\n    // input is validated and typed\n    return await db.users.create({ data: input })\n  })\n```\n\n### 3. Context & Authentication\n\n```typescript\nimport { createAuthMiddleware, createBearerStrategy } from 'raffel'\n\nserver\n  .use(createAuthMiddleware({\n    strategies: [createBearerStrategy({\n      verify: async (token) => {\n        const payload = await verifyJwt(token)\n        return payload ? { authenticated: true, principal: payload.sub, claims: payload } : null\n      }\n    })]\n  }))\n\n  .procedure('users.me')\n    .handler(async (_input, ctx) => {\n      return { userId: ctx.auth?.principal }\n    })\n```\n\n### 4. Streaming\n\n```typescript\n// Server sends multiple responses\nserver.stream('logs.tail')\n  .handler(async function* (input, ctx) {\n    while (!ctx.signal.aborted) {\n      const logs = await getNewLogs(input.filter)\n      for (const log of logs) {\n        yield log\n      }\n      await sleep(1000)\n    }\n  })\n```\n\n### 5. Events\n\n```typescript\n// Fire-and-forget with retries\nserver.event('orders.notify')\n  .delivery('at-least-once')\n  .retryPolicy({ maxAttempts: 5 })\n  .handler(async (payload, ctx, ack) => {\n    await sendNotification(payload)\n    ack()  // Acknowledge success\n  })\n```\n\n### 6. Multiple Protocols\n\n```typescript\nconst server = createServer({ port: 3000 })\n  // HTTP is default\n  .websocket({ path: '/ws' })            // Add WebSocket\n  .jsonrpc({ path: '/rpc' })             // Add JSON-RPC\n  .grpc({ port: 50051 })                 // Add gRPC\n  .configureGraphQL({ path: '/graphql' }) // Add GraphQL\n```\n\n## HTTP Mapping\n\n| Handler | HTTP | Path |\n|---------|------|------|\n| procedure | POST | {basePath}/{name} |\n| stream | GET (SSE) | {basePath}/streams/{name} |\n| event | POST | {basePath}/events/{name} |\n\nBase path defaults to `/`. Set `basePath` in `createServer` to add a prefix.\n\n## Complete Example\n\n```typescript\nimport { createServer, registerValidator, createZodAdapter, createAuthMiddleware, createBearerStrategy, RaffelError } from 'raffel'\nimport { z } from 'zod'\n\n// Setup validation\nregisterValidator(createZodAdapter(z))\n\nconst server = createServer({ port: 3000 })\n  // Providers (DI)\n  .provide('db', async () => {\n    const prisma = new PrismaClient()\n    await prisma.$connect()\n    return prisma\n  }, { onShutdown: (db) => db.$disconnect() })\n\n  // Global middleware\n  .use(createAuthMiddleware({\n    strategies: [createBearerStrategy({ verify: verifyToken })]\n  }))\n\n  // Procedures\n  .procedure('users.list')\n    .output(z.array(UserSchema))\n    .handler(async (input, ctx) => {\n      return await ctx.db.users.findMany()\n    })\n\n  .procedure('users.get')\n    .input(z.object({ id: z.string() }))\n    .output(UserSchema)\n    .handler(async ({ id }, ctx) => {\n      const user = await ctx.db.users.findUnique({ where: { id } })\n      if (!user) throw new RaffelError('NOT_FOUND', `User ${id} not found`)\n      return user\n    })\n\n  .procedure('users.create')\n    .input(CreateUserSchema)\n    .output(UserSchema)\n    .handler(async (input, ctx) => {\n      return await ctx.db.users.create({ data: input })\n    })\n\nawait server.start()\n```\n\n## Next Steps\n\n- **Interceptors**: Add rate limiting, caching, metrics\n- **Streaming**: Real-time data with generators\n- **Events**: Background processing with delivery guarantees\n- **Multi-protocol**: Same handlers on HTTP, WebSocket, gRPC\n- **Observability**: Metrics and distributed tracing\n";
+export declare const quickstartGuide = "# Raffel Quickstart\n\n## Installation\n\n```bash\nnpm i -g raffel\n# or use npx without a global install\npnpm add raffel\nnpx raffel new api my-service\ncd my-service\npnpm install\nnpx raffel inspect src/server.ts\nnpx raffel doctor src/server.ts\nnpx raffel playground src/server.ts --port 4301\nnpx raffel contract-tests src/server.ts\npnpm dev\n# or\nnpm install raffel\n```\n\n## Basic Server\n\nThe recommended flow is:\n\n```bash\nnpx raffel new api my-service\ncd my-service\nnpx raffel inspect src/server.ts\nnpx raffel doctor src/server.ts\nnpx raffel playground src/server.ts --port 4301\nnpx raffel contract-tests src/server.ts\npnpm dev\n```\n\nIf you want the smallest possible manual server, start here:\n\n```typescript\nimport { createServer } from 'raffel'\n\nconst server = createServer({ port: 3000 })\n  .procedure('hello')\n    .handler(async (input, ctx) => {\n      return { message: `Hello, ${input.name || 'World'}!` }\n    })\n\nawait server.start()\nconsole.log('Server running on http://localhost:3000')\n```\n\n## Core Concepts\n\n### 1. Procedures (RPC Endpoints)\n\n```typescript\n// Unary RPC: Input \u2192 Output\nserver.procedure('users.create')\n  .handler(async (input, ctx) => {\n    const services = ctx.services as {\n      users: { create(data: unknown): Promise<unknown> }\n    }\n    return services.users.create(input)\n  })\n```\n\n### 2. Input/Output Validation\n\n```typescript\nimport { z } from 'zod'\nimport { registerValidator, createZodAdapter } from 'raffel'\n\nregisterValidator(createZodAdapter(z))\n\nserver.procedure('users.create')\n  .input(z.object({\n    name: z.string().min(2),\n    email: z.string().email()\n  }))\n  .output(z.object({\n    id: z.string(),\n    name: z.string(),\n    email: z.string()\n  }))\n  .handler(async (input, ctx) => {\n    // input is validated and typed\n    const services = ctx.services as {\n      users: { create(data: unknown): Promise<unknown> }\n    }\n    return services.users.create(input)\n  })\n```\n\n### 3. Context & Authentication\n\n```typescript\nimport { createAuthMiddleware, createBearerStrategy } from 'raffel'\n\nserver\n  .use(createAuthMiddleware({\n    strategies: [createBearerStrategy({\n      verify: async (token) => {\n        const payload = await verifyJwt(token)\n        return payload ? { authenticated: true, principal: payload.sub, claims: payload } : null\n      }\n    })]\n  }))\n\n  .procedure('users.me')\n    .handler(async (_input, ctx) => {\n      return { userId: ctx.auth?.principalId }\n    })\n```\n\n### 4. Streaming\n\n```typescript\n// Server sends multiple responses\nserver.stream('logs.tail')\n  .handler(async function* (input, ctx) {\n    while (!ctx.signal.aborted) {\n      const logs = await getNewLogs(input.filter)\n      for (const log of logs) {\n        yield log\n      }\n      await sleep(1000)\n    }\n  })\n```\n\n### 5. Events\n\n```typescript\n// Fire-and-forget with retries\nserver.event('orders.notify')\n  .delivery('at-least-once')\n  .retryPolicy({ maxAttempts: 5 })\n  .handler(async (payload, ctx, ack) => {\n    await sendNotification(payload)\n    ack()  // Acknowledge success\n  })\n```\n\n### 6. Multiple Protocols\n\n```typescript\nconst server = createServer({ port: 3000 })\n  // HTTP is default\n  .websocket({ path: '/ws' })            // Add WebSocket\n  .jsonrpc({ path: '/rpc' })             // Add JSON-RPC\n  .grpc({ port: 50051 })                 // Add gRPC\n  .configureGraphQL({ path: '/graphql' }) // Add GraphQL\n```\n\n## HTTP Mapping\n\n| Handler | HTTP | Path |\n|---------|------|------|\n| procedure | POST | {basePath}/{name} |\n| stream | GET (SSE) | {basePath}/streams/{name} |\n| event | POST | {basePath}/events/{name} |\n\nBase path defaults to `/`. Set `basePath` in `createServer` to add a prefix.\n\n## Complete Example\n\n```typescript\nimport { createServer, registerValidator, createZodAdapter, createAuthMiddleware, createBearerStrategy, RaffelError } from 'raffel'\nimport { z } from 'zod'\n\n// Setup validation\nregisterValidator(createZodAdapter(z))\n\nconst server = createServer({ port: 3000 })\n  // Providers (DI)\n  .provide('users', async () => createUsersService())\n\n  // Global middleware\n  .use(createAuthMiddleware({\n    strategies: [createBearerStrategy({ verify: verifyToken })]\n  }))\n\n  // Procedures\n  .procedure('users.list')\n    .output(z.array(UserSchema))\n    .handler(async (_input, ctx) => {\n      const services = ctx.services as {\n        users: { list(): Promise<unknown[]> }\n      }\n      return services.users.list()\n    })\n\n  .procedure('users.get')\n    .input(z.object({ id: z.string() }))\n    .output(UserSchema)\n    .handler(async ({ id }, ctx) => {\n      const services = ctx.services as {\n        users: { get(id: string): Promise<unknown> }\n      }\n      const user = await services.users.get(id)\n      if (!user) throw new RaffelError('NOT_FOUND', `User ${id} not found`)\n      return user\n    })\n\n  .procedure('users.create')\n    .input(CreateUserSchema)\n    .output(UserSchema)\n    .handler(async (input, ctx) => {\n      const services = ctx.services as {\n        users: { create(data: unknown): Promise<unknown> }\n      }\n      return services.users.create(input)\n    })\n\nawait server.start()\n```\n\n## Next Steps\n\n- **Interceptors**: Add rate limiting, caching, metrics\n- **Streaming**: Real-time data with generators\n- **Events**: Background processing with delivery guarantees\n- **Multi-protocol**: Same handlers on HTTP, WebSocket, gRPC, TCP, and UDP\n- **Observability**: Metrics and distributed tracing\n- **Spec-driven mocks**: Start mock endpoints from OpenAPI/USD with `createMockServer()`\n";
 export declare const boilerplates: {
     'basic-api': {
         title: string;

package/dist/mcp/docs/quickstart.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"quickstart.d.ts","sourceRoot":"","sources":["../../../src/mcp/docs/quickstart.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,eAAO,MAAM,eAAe,oiJA2L3B,CAAA;AAED,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+dxB,CAAA;AAED,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,OAAO,YAAY,GAC9B,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,GAAG,SAAS,CAE9D;AAED,wBAAgB,gBAAgB,IAAI,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CAM9F"}
+{"version":3,"file":"quickstart.d.ts","sourceRoot":"","sources":["../../../src/mcp/docs/quickstart.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,eAAO,MAAM,eAAe,ykLA+N3B,CAAA;AAED,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmexB,CAAA;AAED,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,OAAO,YAAY,GAC9B,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,GAAG,SAAS,CAE9D;AAED,wBAAgB,gBAAgB,IAAI,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CAM9F"}

package/dist/mcp/docs/quickstart.js

@@ -8,13 +8,37 @@ export const quickstartGuide = `# Raffel Quickstart
 ## Installation
 
 \`\`\`bash
+npm i -g raffel
+# or use npx without a global install
 pnpm add raffel
+npx raffel new api my-service
+cd my-service
+pnpm install
+npx raffel inspect src/server.ts
+npx raffel doctor src/server.ts
+npx raffel playground src/server.ts --port 4301
+npx raffel contract-tests src/server.ts
+pnpm dev
 # or
 npm install raffel
 \`\`\`
 
 ## Basic Server
 
+The recommended flow is:
+
+\`\`\`bash
+npx raffel new api my-service
+cd my-service
+npx raffel inspect src/server.ts
+npx raffel doctor src/server.ts
+npx raffel playground src/server.ts --port 4301
+npx raffel contract-tests src/server.ts
+pnpm dev
+\`\`\`
+
+If you want the smallest possible manual server, start here:
+
 \`\`\`typescript
 import { createServer } from 'raffel'
 
@@ -36,7 +60,10 @@ console.log('Server running on http://localhost:3000')
 // Unary RPC: Input → Output
 server.procedure('users.create')
   .handler(async (input, ctx) => {
-    return await db.users.create({ data: input })
+    const services = ctx.services as {
+      users: { create(data: unknown): Promise<unknown> }
+    }
+    return services.users.create(input)
   })
 \`\`\`
 
@@ -60,7 +87,10 @@ server.procedure('users.create')
   }))
   .handler(async (input, ctx) => {
     // input is validated and typed
-    return await db.users.create({ data: input })
+    const services = ctx.services as {
+      users: { create(data: unknown): Promise<unknown> }
+    }
+    return services.users.create(input)
   })
 \`\`\`
 
@@ -81,7 +111,7 @@ server
 
   .procedure('users.me')
     .handler(async (_input, ctx) => {
-      return { userId: ctx.auth?.principal }
+      return { userId: ctx.auth?.principalId }
     })
 \`\`\`
 
@@ -146,11 +176,7 @@ registerValidator(createZodAdapter(z))
 
 const server = createServer({ port: 3000 })
   // Providers (DI)
-  .provide('db', async () => {
-    const prisma = new PrismaClient()
-    await prisma.$connect()
-    return prisma
-  }, { onShutdown: (db) => db.$disconnect() })
+  .provide('users', async () => createUsersService())
 
   // Global middleware
   .use(createAuthMiddleware({
@@ -160,15 +186,21 @@ const server = createServer({ port: 3000 })
   // Procedures
   .procedure('users.list')
     .output(z.array(UserSchema))
-    .handler(async (input, ctx) => {
-      return await ctx.db.users.findMany()
+    .handler(async (_input, ctx) => {
+      const services = ctx.services as {
+        users: { list(): Promise<unknown[]> }
+      }
+      return services.users.list()
     })
 
   .procedure('users.get')
     .input(z.object({ id: z.string() }))
     .output(UserSchema)
     .handler(async ({ id }, ctx) => {
-      const user = await ctx.db.users.findUnique({ where: { id } })
+      const services = ctx.services as {
+        users: { get(id: string): Promise<unknown> }
+      }
+      const user = await services.users.get(id)
       if (!user) throw new RaffelError('NOT_FOUND', \`User \${id} not found\`)
       return user
     })
@@ -177,7 +209,10 @@ const server = createServer({ port: 3000 })
     .input(CreateUserSchema)
     .output(UserSchema)
     .handler(async (input, ctx) => {
-      return await ctx.db.users.create({ data: input })
+      const services = ctx.services as {
+        users: { create(data: unknown): Promise<unknown> }
+      }
+      return services.users.create(input)
     })
 
 await server.start()
@@ -188,8 +223,9 @@ await server.start()
 - **Interceptors**: Add rate limiting, caching, metrics
 - **Streaming**: Real-time data with generators
 - **Events**: Background processing with delivery guarantees
-- **Multi-protocol**: Same handlers on HTTP, WebSocket, gRPC
+- **Multi-protocol**: Same handlers on HTTP, WebSocket, gRPC, TCP, and UDP
 - **Observability**: Metrics and distributed tracing
+- **Spec-driven mocks**: Start mock endpoints from OpenAPI/USD with \`createMockServer()\`
 `;
 export const boilerplates = {
     'basic-api': {
@@ -362,15 +398,14 @@ const server = createServer({ port: 3000 })
   .procedure('users.me')
     .handler(async (_input, ctx) => {
       return {
-        userId: ctx.auth?.principal,
-        email: ctx.auth?.claims?.email,
-        roles: ctx.auth?.claims?.roles,
+        userId: ctx.auth?.principalId,
+        roles: ctx.auth?.roles,
       }
     })
 
   .procedure('admin.stats')
     .handler(async (_input, ctx) => {
-      if (!ctx.auth?.claims?.roles?.includes('admin')) {
+      if (!ctx.auth?.roles?.includes('admin')) {
         throw new RaffelError('PERMISSION_DENIED', 'Admin access required')
       }
       return { users: 100, orders: 500 }
@@ -431,8 +466,9 @@ const server = createServer({ port: 3000 })
   })
 
   .procedure('users.list')
-    .handler(async (input, ctx) => {
-      return await ctx.db.user.findMany({
+    .handler(async (_input, ctx) => {
+      const services = ctx.services as { db: PrismaClient }
+      return await services.db.user.findMany({
         orderBy: { createdAt: 'desc' }
       })
     })
@@ -440,7 +476,8 @@ const server = createServer({ port: 3000 })
   .procedure('users.get')
     .input(z.object({ id: z.string() }))
     .handler(async ({ id }, ctx) => {
-      const user = await ctx.db.user.findUnique({ where: { id } })
+      const services = ctx.services as { db: PrismaClient }
+      const user = await services.db.user.findUnique({ where: { id } })
       if (!user) throw new RaffelError('NOT_FOUND', \`User \${id} not found\`)
       return user
     })
@@ -448,13 +485,14 @@ const server = createServer({ port: 3000 })
   .procedure('users.create')
     .input(CreateUserInput)
     .handler(async (input, ctx) => {
-      const existing = await ctx.db.user.findUnique({
+      const services = ctx.services as { db: PrismaClient }
+      const existing = await services.db.user.findUnique({
         where: { email: input.email }
       })
       if (existing) {
         throw new RaffelError('ALREADY_EXISTS', 'Email already registered')
       }
-      return await ctx.db.user.create({ data: input })
+      return await services.db.user.create({ data: input })
     })
 
   .procedure('users.update')
@@ -464,8 +502,9 @@ const server = createServer({ port: 3000 })
       email: z.string().email().optional()
     }))
     .handler(async ({ id, ...data }, ctx) => {
+      const services = ctx.services as { db: PrismaClient }
       try {
-        return await ctx.db.user.update({ where: { id }, data })
+        return await services.db.user.update({ where: { id }, data })
       } catch {
         throw new RaffelError('NOT_FOUND', \`User \${id} not found\`)
       }
@@ -474,8 +513,9 @@ const server = createServer({ port: 3000 })
   .procedure('users.delete')
     .input(z.object({ id: z.string() }))
     .handler(async ({ id }, ctx) => {
+      const services = ctx.services as { db: PrismaClient }
       try {
-        await ctx.db.user.delete({ where: { id } })
+        await services.db.user.delete({ where: { id } })
         return { success: true }
       } catch {
         throw new RaffelError('NOT_FOUND', \`User \${id} not found\`)
@@ -539,7 +579,7 @@ const server = createServer({ port: 3000 })
         id: crypto.randomUUID(),
         channel: input.channel,
         message: input.message,
-        sender: ctx.auth?.principal ?? 'anonymous',
+        sender: ctx.auth?.principalId ?? 'anonymous',
         timestamp: new Date().toISOString()
       }
 

package/dist/mcp/docs/quickstart.js.map

@@ -1 +1 @@
-{"version":3,"file":"quickstart.js","sourceRoot":"","sources":["../../../src/mcp/docs/quickstart.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,CAAC,MAAM,eAAe,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2L9B,CAAA;AAED,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,WAAW,EAAE;QACX,KAAK,EAAE,gBAAgB;QACvB,WAAW,EAAE,oDAAoD;QACjE,KAAK,EAAE;YACL,eAAe,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiFtB;YACK,cAAc,EAAE;;;;;;;;;;;;;;;;EAgBpB;SACG;KACF;IACD,WAAW,EAAE;QACX,KAAK,EAAE,yBAAyB;QAChC,WAAW,EAAE,0CAA0C;QACvD,KAAK,EAAE;YACL,eAAe,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6EtB;SACI;KACF;IACD,aAAa,EAAE;QACb,KAAK,EAAE,0BAA0B;QACjC,WAAW,EAAE,oDAAoD;QACjE,KAAK,EAAE;YACL,eAAe,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmGtB;YACK,sBAAsB,EAAE;;;;;;;;;;;;;;;;CAgB7B;SACI;KACF;IACD,oBAAoB,EAAE;QACpB,KAAK,EAAE,4BAA4B;QACnC,WAAW,EAAE,iDAAiD;QAC9D,KAAK,EAAE;YACL,eAAe,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4EtB;SACI;KACF;IACD,gBAAgB,EAAE;QAChB,KAAK,EAAE,uBAAuB;QAC9B,WAAW,EAAE,8DAA8D;QAC3E,KAAK,EAAE;YACL,eAAe,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4EtB;SACI;KACF;CACF,CAAA;AAED,MAAM,UAAU,cAAc,CAC5B,IAA+B;IAE/B,OAAO,YAAY,CAAC,IAAI,CAAC,CAAA;AAC3B,CAAC;AAED,MAAM,UAAU,gBAAgB;IAC9B,OAAO,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;QACvD,IAAI;QACJ,KAAK,EAAE,EAAE,CAAC,KAAK;QACf,WAAW,EAAE,EAAE,CAAC,WAAW;KAC5B,CAAC,CAAC,CAAA;AACL,CAAC"}
+{"version":3,"file":"quickstart.js","sourceRoot":"","sources":["../../../src/mcp/docs/quickstart.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,CAAC,MAAM,eAAe,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+N9B,CAAA;AAED,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,WAAW,EAAE;QACX,KAAK,EAAE,gBAAgB;QACvB,WAAW,EAAE,oDAAoD;QACjE,KAAK,EAAE;YACL,eAAe,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiFtB;YACK,cAAc,EAAE;;;;;;;;;;;;;;;;EAgBpB;SACG;KACF;IACD,WAAW,EAAE;QACX,KAAK,EAAE,yBAAyB;QAChC,WAAW,EAAE,0CAA0C;QACvD,KAAK,EAAE;YACL,eAAe,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4EtB;SACI;KACF;IACD,aAAa,EAAE;QACb,KAAK,EAAE,0BAA0B;QACjC,WAAW,EAAE,oDAAoD;QACjE,KAAK,EAAE;YACL,eAAe,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwGtB;YACK,sBAAsB,EAAE;;;;;;;;;;;;;;;;CAgB7B;SACI;KACF;IACD,oBAAoB,EAAE;QACpB,KAAK,EAAE,4BAA4B;QACnC,WAAW,EAAE,iDAAiD;QAC9D,KAAK,EAAE;YACL,eAAe,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4EtB;SACI;KACF;IACD,gBAAgB,EAAE;QAChB,KAAK,EAAE,uBAAuB;QAC9B,WAAW,EAAE,8DAA8D;QAC3E,KAAK,EAAE;YACL,eAAe,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4EtB;SACI;KACF;CACF,CAAA;AAED,MAAM,UAAU,cAAc,CAC5B,IAA+B;IAE/B,OAAO,YAAY,CAAC,IAAI,CAAC,CAAA;AAC3B,CAAC;AAED,MAAM,UAAU,gBAAgB;IAC9B,OAAO,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;QACvD,IAAI;QACJ,KAAK,EAAE,EAAE,CAAC,KAAK;QACf,WAAW,EAAE,EAAE,CAAC,WAAW;KAC5B,CAAC,CAAC,CAAA;AACL,CAAC"}

package/dist/mcp/resources/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/mcp/resources/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAe1F,UAAU,aAAa;IACrB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,MAAM,CAAA;CAChB;AAsHD,wBAAgB,UAAU,IAAI,aAAa,EAAE,CAG5C;AAED,wBAAgB,eAAe,IAAI;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,EAAE,CAGxF;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKnE;AAID,wBAAgB,kBAAkB,IAAI,WAAW,EAAE,CAkElD;AAID,wBAAgB,oBAAoB,IAAI,mBAAmB,EAAE,CAuC5D;AA+fD,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,qBAAqB,GAAG,IAAI,CA4KtE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/mcp/resources/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAe1F,UAAU,aAAa;IACrB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,MAAM,CAAA;CAChB;AAmMD,wBAAgB,UAAU,IAAI,aAAa,EAAE,CAG5C;AAED,wBAAgB,eAAe,IAAI;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,EAAE,CAGxF;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKnE;AAID,wBAAgB,kBAAkB,IAAI,WAAW,EAAE,CAkElD;AAID,wBAAgB,oBAAoB,IAAI,mBAAmB,EAAE,CAuC5D;AA+fD,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,qBAAqB,GAAG,IAAI,CA4KtE"}