@pikku/core 0.11.0 → 0.11.1

package/src/wirings/cli/cli.types.ts

@@ -2,7 +2,6 @@ import {
   CorePikkuMiddleware,
   CoreSingletonServices,
   CoreUserSession,
-  PikkuDocs,
   CoreServices,
   MiddlewareMetadata,
   PermissionMetadata,
@@ -44,7 +43,7 @@ export interface CLIPositional {
 }
 
 /**
- * CLI interaction context
+ * CLI wire context
  */
 export type PikkuCLI = {
   program: string
@@ -74,8 +73,9 @@ export interface CLICommandMeta {
   positionals: CLIPositional[]
   options: Record<string, CLIOption>
   renderName?: string
+  summary?: string
   description?: string
-  docs?: PikkuDocs
+  errors?: string[]
   tags?: string[]
   subcommands?: Record<string, CLICommandMeta>
   middleware?: MiddlewareMetadata[] // Pre-resolved middleware chain (tag + explicit)
@@ -131,8 +131,8 @@ export type CorePikkuCLIRender<
 export type ExtractFunctionInput<Func> =
   Func extends CorePikkuFunctionConfig<infer FuncType, any, any>
     ? FuncType extends
-        | CorePikkuFunction<infer Input, any, any, any, any>
-        | CorePikkuFunctionSessionless<infer Input, any, any, any, any>
+        | CorePikkuFunction<infer Input, any, any, any>
+        | CorePikkuFunctionSessionless<infer Input, any, any, any>
       ? Input
       : never
     : never
@@ -198,8 +198,8 @@ export type ValidateParameters<Params extends string, Input> =
 export type ExtractFunctionOutput<Func> =
   Func extends CorePikkuFunctionConfig<infer FuncType, any, any>
     ? FuncType extends
-        | CorePikkuFunction<any, infer Output, any, any, any>
-        | CorePikkuFunctionSessionless<any, infer Output, any, any, any>
+        | CorePikkuFunction<any, infer Output, any, any>
+        | CorePikkuFunctionSessionless<any, infer Output, any, any>
       ? Output
       : never
     : never
@@ -210,7 +210,10 @@ export type ExtractFunctionOutput<Func> =
  */
 export type CoreCLICommandConfig<
   FuncConfig,
-  PikkuMiddleware extends CorePikkuMiddleware<any> = CorePikkuMiddleware<any>,
+  PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<
+    any,
+    any
+  >,
   PikkuCLIRender extends CorePikkuCLIRender<any, any, any> = CorePikkuCLIRender<
     any,
     any
@@ -245,8 +248,8 @@ export interface CoreCLICommand<
   In,
   Out,
   PikkuFunctionConfig extends CorePikkuFunctionConfig<
-    | CorePikkuFunction<In, Out, any, any, any>
-    | CorePikkuFunctionSessionless<In, Out, any, any, any>
+    | CorePikkuFunction<In, Out, any, any>
+    | CorePikkuFunctionSessionless<In, Out, any, any>
   >,
   PikkuPermission extends CorePikkuPermission<any, any, any>,
   PikkuMiddleware extends CorePikkuMiddleware,
@@ -264,7 +267,9 @@ export interface CoreCLICommand<
   middleware?: PikkuMiddleware[]
   permissions?: Record<string, PikkuPermission | PikkuPermission[]>
   auth?: boolean
-  docs?: PikkuDocs
+  summary?: string
+  errors?: string[]
+  tags?: string[]
   subcommands?: Subcommands
   isDefault?: boolean
 }
@@ -276,8 +281,8 @@ export type CLICommandShorthand<
   In,
   Out,
   PikkuFunctionConfig extends CorePikkuFunctionConfig<
-    | CorePikkuFunction<In, Out, any, any, any>
-    | CorePikkuFunctionSessionless<In, Out, any, any, any>
+    | CorePikkuFunction<In, Out, any, any>
+    | CorePikkuFunctionSessionless<In, Out, any, any>
   >,
 > = PikkuFunctionConfig
 
@@ -288,8 +293,8 @@ export type CLICommandDefinition<
   In,
   Out,
   PikkuFunctionConfig extends CorePikkuFunctionConfig<
-    | CorePikkuFunction<In, Out, any, any, any>
-    | CorePikkuFunctionSessionless<In, Out, any, any, any>
+    | CorePikkuFunction<In, Out, any, any>
+    | CorePikkuFunctionSessionless<In, Out, any, any>
   >,
   PikkuPermission extends CorePikkuPermission<any, any, any>,
   PikkuMiddleware extends CorePikkuMiddleware,
@@ -325,7 +330,8 @@ export interface CoreCLI<
   options?: CLIOptions<Options>
   middleware?: PikkuMiddleware[]
   render?: PikkuCLIRender
-  docs?: PikkuDocs
+  summary?: string
+  errors?: string[]
   tags?: string[]
 }
 

package/src/wirings/http/http-runner.test.ts

@@ -11,8 +11,8 @@ import {
 import { addFunction } from '../../function/function-runner.js'
 import { httpRouter } from './routers/http-router.js'
 
-const sessionMiddleware: CorePikkuMiddleware = async (services, _, next) => {
-  services.userSession.set({ userId: 'test' } as any)
+const sessionMiddleware: CorePikkuMiddleware = async (services, wire, next) => {
+  wire.session?.set({ userId: 'test' } as any)
   await next()
 }
 
@@ -43,7 +43,7 @@ const setHTTPFunctionMap = (func: any) => {
 
 describe('fetch', () => {
   let singletonServices: any
-  let createSessionServices: any
+  let createWireServices: any
   let request: any
   let response: any
 
@@ -59,7 +59,7 @@ describe('fetch', () => {
       },
     }
 
-    createSessionServices = async () => ({})
+    createWireServices = async () => ({})
     request = new PikkuMockRequest('/test', 'get')
     response = new PikkuMockResponse()
 
@@ -77,7 +77,7 @@ describe('fetch', () => {
       async () =>
         fetch(request, {
           singletonServices,
-          createSessionServices,
+          createWireServices,
           bubbleErrors: true,
         }),
       NotFoundError
@@ -99,7 +99,7 @@ describe('fetch', () => {
 
     const result = await fetch(request, {
       singletonServices,
-      createSessionServices,
+      createWireServices,
     })
 
     assert.deepStrictEqual(await result.json(), { success: true })
@@ -122,7 +122,7 @@ describe('fetch', () => {
 
     await fetch(request, {
       singletonServices,
-      createSessionServices,
+      createWireServices,
     })
 
     assert.strictEqual(await permissions.test(), true)
@@ -143,7 +143,7 @@ describe('fetch', () => {
       async () =>
         fetch(request, {
           singletonServices,
-          createSessionServices,
+          createWireServices,
           bubbleErrors: true,
         }),
       error

package/src/wirings/http/http-runner.ts

@@ -18,24 +18,23 @@ import {
   CoreUserSession,
   CorePikkuMiddleware,
   CorePikkuMiddlewareGroup,
-  SessionServices,
+  WireServices,
+  PikkuWire,
   PikkuWiringTypes,
-  PikkuInteraction,
 } from '../../types/core.types.js'
 import { NotFoundError } from '../../errors/errors.js'
 import {
-  closeSessionServices,
+  closeWireServices,
   createWeakUID,
   isSerializable,
 } from '../../utils.js'
-import { PikkuUserSessionService } from '../../services/user-session-service.js'
+import { PikkuSessionService } from '../../services/user-session-service.js'
 import { handleHTTPError } from '../../handle-error.js'
 import { pikkuState } from '../../pikku-state.js'
 import { PikkuFetchHTTPResponse } from './pikku-fetch-http-response.js'
 import { PikkuFetchHTTPRequest } from './pikku-fetch-http-request.js'
 import { PikkuChannel } from '../channel/channel.types.js'
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js'
-import { rpcService } from '../rpc/rpc-runner.js'
 import { httpRouter } from './routers/http-router.js'
 
 /**
@@ -203,16 +202,16 @@ const getMatchingRoute = (requestType: string, requestPath: string) => {
 }
 
 /**
- * Combines the request and response objects into a single HTTP interaction object.
+ * Combines the request and response objects into a single HTTP wire object.
  *
  * This utility function creates an object that holds both the HTTP request and response,
  * which simplifies passing these around through middleware and route execution.
  *
  * @param {PikkuHTTPRequest | undefined} request - The HTTP request object.
  * @param {PikkuHTTPResponse | undefined} response - The HTTP response object.
- * @returns {PikkuHTTP | undefined} The combined HTTP interaction object or undefined if none provided.
+ * @returns {PikkuHTTP | undefined} The combined HTTP wire object or undefined if none provided.
  */
-export const createHTTPInteraction = (
+export const createHTTPWire = (
   request: PikkuHTTPRequest | undefined,
   response: PikkuHTTPResponse | undefined
 ): PikkuHTTP | undefined => {
@@ -246,15 +245,15 @@ export const createHTTPInteraction = (
  *
  * @param {Object} services - A collection of shared services and utilities.
  * @param {Object} matchedRoute - Contains route details, URL parameters, and optional schema.
- * @param {PikkuHTTP | undefined} http - The HTTP interaction object.
+ * @param {PikkuHTTP | undefined} http - The HTTP wire object.
  * @param {Object} options - Options for route execution (e.g., whether to coerce query strings to arrays).
- * @returns {Promise<any>} An object containing the route handler result and session services (if any).
+ * @returns {Promise<any>} An object containing the route handler result and wire services (if any).
  * @throws Throws errors like MissingSessionError or ForbiddenError on validation failures.
  */
 const executeRoute = async (
   services: {
     singletonServices: any
-    createSessionServices: Function
+    createWireServices?: any
     skipUserSession: boolean
     requestId: string
   },
@@ -269,17 +268,13 @@ const executeRoute = async (
     coerceDataFromSchema: boolean
   }
 ) => {
-  const userSession = new PikkuUserSessionService<CoreUserSession>()
+  const userSession = new PikkuSessionService<CoreUserSession>()
   const { params, route, meta } = matchedRoute
-  const {
-    singletonServices,
-    createSessionServices,
-    skipUserSession,
-    requestId,
-  } = services
+  const { singletonServices, createWireServices, skipUserSession, requestId } =
+    services
 
   const requiresSession = route.auth !== false
-  let sessionServices: any
+  let wireServices: any
   let result: any
 
   // Attach URL parameters to the request object
@@ -324,38 +319,16 @@ const executeRoute = async (
     }
   }
 
-  const interaction: PikkuInteraction = { http, channel }
-
-  const getAllServices = async (session?: CoreUserSession) => {
-    // Create session-specific services for handling the request
-    sessionServices = await createSessionServices(
-      { ...singletonServices, userSession, channel },
-      { http },
-      session
-    )
-
-    return rpcService.injectRPCService(
-      {
-        ...singletonServices,
-        ...sessionServices,
-        http,
-        userSession,
-        channel,
-      },
-      interaction,
-      route.auth
-    )
-  }
+  const wire: PikkuWire = { http, channel, session: userSession }
 
   result = await runPikkuFunc(
-    PikkuWiringTypes.http,
+    'http',
     `${meta.method}:${meta.route}`,
     meta.pikkuFuncName,
     {
       singletonServices,
-      getAllServices,
+      createWireServices,
       auth: route.auth !== false,
-      userSession,
       data,
       inheritedMiddleware: meta.middleware,
       wireMiddleware: route.middleware,
@@ -363,7 +336,7 @@ const executeRoute = async (
       wirePermissions: route.permissions,
       coerceDataFromSchema: options.coerceDataFromSchema,
       tags: route.tags,
-      interaction,
+      wire,
     }
   )
 
@@ -378,7 +351,7 @@ const executeRoute = async (
   // TODO: Evaluate if the response stream should be explicitly ended.
   // http?.response?.end()
 
-  return sessionServices ? { result, sessionServices } : { result }
+  return wireServices ? { result, wireServices } : { result }
 }
 
 /**
@@ -431,11 +404,11 @@ export const pikkuFetch = async <In, Out>(
  * middleware execution, error handling, and session service cleanup.
  *
  * This function does the following:
- *  - Wraps the incoming request and response into an HTTP interaction object.
+ *  - Wraps the incoming request and response into an HTTP wire object.
  *  - Determines the correct route based on HTTP method and path.
  *  - Executes middleware and the route handler.
  *  - Catches and handles errors, optionally bubbling them if configured.
- *  - Cleans up any session services created during processing.
+ *  - Cleans up any wire services created during processing.
  *
  * @template In Expected input data type.
  * @template Out Expected output data type.
@@ -449,7 +422,7 @@ export const fetchData = async <In, Out>(
   response: PikkuHTTPResponse,
   {
     singletonServices,
-    createSessionServices,
+    createWireServices,
     skipUserSession = false,
     respondWith404 = true,
     logWarningsForStatusCodes = [],
@@ -462,11 +435,11 @@ export const fetchData = async <In, Out>(
     (request as any).getHeader?.('x-request-id') ||
     generateRequestId?.() ||
     createWeakUID()
-  let sessionServices: SessionServices<typeof singletonServices> | undefined
+  let wireServices: WireServices<typeof singletonServices> | undefined
   let result: Out
 
-  // Combine the request and response into one interaction object
-  const http = createHTTPInteraction(
+  // Combine the request and response into one wire object
+  const http = createHTTPWire(
     request instanceof Request ? new PikkuFetchHTTPRequest(request) : request,
     response
   )
@@ -487,10 +460,10 @@ export const fetchData = async <In, Out>(
     }
 
     // Execute the matched route along with its middleware and session management
-    ;({ result, sessionServices } = await executeRoute(
+    ;({ result, wireServices } = await executeRoute(
       {
         singletonServices,
-        createSessionServices,
+        createWireServices,
         skipUserSession,
         requestId,
       },
@@ -513,8 +486,8 @@ export const fetchData = async <In, Out>(
     )
   } finally {
     // Clean up any session-specific services created during processing
-    if (sessionServices) {
-      await closeSessionServices(singletonServices.logger, sessionServices)
+    if (wireServices) {
+      await closeWireServices(singletonServices.logger, wireServices)
     }
   }
 }

package/src/wirings/http/http.types.ts

@@ -1,14 +1,12 @@
 import type { SerializeOptions } from 'cookie'
 import type { PikkuError } from '../../errors/error-handler.js'
 import type {
-  PikkuDocs,
   CoreServices,
   CoreSingletonServices,
   CoreUserSession,
-  CreateSessionServices,
+  CreateWireServices,
   CorePikkuMiddleware,
-  MiddlewareMetadata,
-  PermissionMetadata,
+  CommonWireMeta,
 } from '../../types/core.types.js'
 import type {
   CorePikkuFunction,
@@ -46,7 +44,7 @@ export type RunHTTPWiringOptions = Partial<{
 
 export type RunHTTPWiringParams = {
   singletonServices: CoreSingletonServices
-  createSessionServices: CreateSessionServices<
+  createWireServices: CreateWireServices<
     CoreSingletonServices,
     CoreServices<CoreSingletonServices>,
     CoreUserSession
@@ -83,7 +81,7 @@ export type CoreHTTPFunction = {
   }>
 }
 /**
- * Represents a http interaction within Pikku, including a request and response.
+ * Represents a http wire within Pikku, including a request and response.
  */
 export interface PikkuHTTP<In = unknown> {
   request?: PikkuHTTPRequest<In>
@@ -123,14 +121,12 @@ export type CoreHTTPFunctionWiring<
     In,
     Out,
     any,
-    any,
     any
   > = CorePikkuFunction<In, Out>,
   PikkuFunctionSessionless extends CorePikkuFunctionSessionless<
     In,
     Out,
     any,
-    any,
     any
   > = CorePikkuFunctionSessionless<In, Out>,
   PikkuPermission extends CorePikkuPermission<
@@ -242,18 +238,13 @@ export type HTTPFunctionMetaInputTypes = {
 /**
  * Represents metadata for a set of HTTP wirings, including HTTP wiring details, methods, input/output types, and documentation.
  */
-export type HTTPWiringMeta = {
-  pikkuFuncName: string
+export type HTTPWiringMeta = CommonWireMeta & {
   route: string
   method: HTTPMethod
   params?: string[]
   query?: string[]
   inputTypes?: HTTPFunctionMetaInputTypes
-  docs?: PikkuDocs
-  tags?: string[]
   sse?: true
-  middleware?: MiddlewareMetadata[] // Pre-resolved middleware chain (global + route + tag + explicit)
-  permissions?: PermissionMetadata[] // Pre-resolved permission chain (global + route + tag + explicit)
 }
 export type HTTPWiringsMeta = Record<HTTPMethod, Record<string, HTTPWiringMeta>>
 

package/src/wirings/mcp/mcp-runner.ts

@@ -1,10 +1,9 @@
 import {
-  PikkuInteraction,
-  PikkuWiringTypes,
+  PikkuWire,
   type CoreServices,
   type CoreSingletonServices,
   type CoreUserSession,
-  type CreateSessionServices,
+  type CreateWireServices,
 } from '../../types/core.types.js'
 import type {
   CoreMCPResource,
@@ -20,11 +19,11 @@ import type {
   CorePikkuFunctionSessionless,
 } from '../../function/functions.types.js'
 import { getErrorResponse } from '../../errors/error-handler.js'
-import { closeSessionServices } from '../../utils.js'
+import { closeWireServices } from '../../utils.js'
 import { pikkuState } from '../../pikku-state.js'
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js'
-import { rpcService } from '../rpc/rpc-runner.js'
 import { BadRequestError, NotFoundError } from '../../errors/errors.js'
+import { PikkuSessionService } from '../../services/user-session-service.js'
 
 export class MCPError extends Error {
   constructor(public readonly error: JsonRpcErrorResponse) {
@@ -37,7 +36,7 @@ export class MCPError extends Error {
 export type RunMCPEndpointParams<Tools extends string = any> = {
   singletonServices: CoreSingletonServices
   mcp?: PikkuMCP<Tools>
-  createSessionServices?: CreateSessionServices<
+  createWireServices?: CreateWireServices<
     CoreSingletonServices,
     CoreServices<CoreSingletonServices>,
     CoreUserSession
@@ -209,13 +208,9 @@ async function runMCPPikkuFunc(
   name: string,
   mcp: CoreMCPResource | CoreMCPTool | CoreMCPPrompt | undefined,
   pikkuFuncName: string | undefined,
-  {
-    singletonServices,
-    createSessionServices,
-    mcp: mcpInteraction,
-  }: RunMCPEndpointParams
+  { singletonServices, createWireServices, mcp: mcpWire }: RunMCPEndpointParams
 ): Promise<JsonRpcResponse> {
-  let sessionServices: any
+  let wireServices: any
 
   try {
     // Validate JSON-RPC request structure
@@ -239,23 +234,9 @@ async function runMCPPikkuFunc(
 
     singletonServices.logger.debug(`Running MCP ${type}: ${name}`)
 
-    const interaction: PikkuInteraction = { mcp: mcpInteraction }
-
-    const getAllServices = async () => {
-      sessionServices = await createSessionServices?.(
-        singletonServices,
-        interaction,
-        undefined
-      )
-
-      return rpcService.injectRPCService(
-        {
-          ...singletonServices,
-          ...sessionServices,
-          mcp: mcpInteraction,
-        },
-        interaction
-      )
+    const wire: PikkuWire = {
+      mcp: mcpWire,
+      session: new PikkuSessionService(),
     }
 
     // Get metadata for the MCP endpoint to access pre-resolved middleware
@@ -268,23 +249,17 @@ async function runMCPPikkuFunc(
       meta = pikkuState('mcp', 'promptsMeta')[name]
     }
 
-    const result = await runPikkuFunc(
-      PikkuWiringTypes.mcp,
-      `${type}:${name}`,
-      pikkuFuncName,
-      {
-        singletonServices,
-        getAllServices,
-        userSession: undefined, // TODO
-        data: () => request.params,
-        inheritedMiddleware: meta?.middleware,
-        wireMiddleware: mcp.middleware,
-        inheritedPermissions: meta?.permissions,
-        wirePermissions: mcp.permissions,
-        tags: mcp.tags,
-        interaction,
-      }
-    )
+    const result = await runPikkuFunc('mcp', `${type}:${name}`, pikkuFuncName, {
+      singletonServices,
+      createWireServices,
+      data: () => request.params,
+      inheritedMiddleware: meta?.middleware,
+      wireMiddleware: mcp.middleware,
+      inheritedPermissions: meta?.permissions,
+      wirePermissions: mcp.permissions,
+      tags: mcp.tags,
+      wire,
+    })
 
     return {
       id: request.id,
@@ -316,8 +291,8 @@ async function runMCPPikkuFunc(
       })
     }
   } finally {
-    if (sessionServices) {
-      await closeSessionServices(singletonServices.logger, sessionServices)
+    if (wireServices) {
+      await closeWireServices(singletonServices.logger, wireServices)
     }
   }
 }

package/src/wirings/mcp/mcp.types.ts

@@ -104,6 +104,8 @@ export type CoreMCPResource<
   uri: string
   title: string
   description: string
+  summary?: string
+  errors?: string[]
   mimeType?: string
   size?: number
   streaming?: boolean
@@ -126,6 +128,8 @@ export type CoreMCPTool<
   name: string
   title?: string
   description: string
+  summary?: string
+  errors?: string[]
   func: PikkuFunctionConfig
   tags?: string[]
   streaming?: boolean
@@ -145,6 +149,8 @@ export type CoreMCPPrompt<
 > = {
   name: string
   description: string
+  summary?: string
+  errors?: string[]
   func: PikkuFunctionConfig
   tags?: string[]
   middleware?: PikkuMiddleware[]