@pikku/core 0.11.1 → 0.12.0

package/src/wirings/http/log-http-routes.ts

@@ -6,7 +6,7 @@ import { Logger } from '../../services/index.js'
  * @param logger - A logger for logging information.
  */
 export const logRoutes = (logger: Logger) => {
-  const routesByType = pikkuState('http', 'routes')
+  const routesByType = pikkuState(null, 'http', 'routes')
   if (routesByType.size === 0) {
     logger.info('No routes added')
     return

package/src/wirings/http/routers/path-to-regex.test.ts

@@ -23,6 +23,7 @@ describe('PathToRegexRouter', () => {
     test('should correctly identify static routes', () => {
       // Setup test routes
       pikkuState(
+        null,
         'http',
         'routes',
         new Map([
@@ -36,8 +37,8 @@ describe('PathToRegexRouter', () => {
           ],
         ])
       )
-      pikkuState('http', 'middleware', new Map())
-      pikkuState('channel', 'channels', new Map())
+      pikkuState(null, 'http', 'middleware', new Map())
+      pikkuState(null, 'channel', 'channels', new Map())
 
       router.initialize()
 
@@ -56,6 +57,7 @@ describe('PathToRegexRouter', () => {
     test('should handle dynamic routes with parameters', () => {
       // Setup test routes with parameters
       pikkuState(
+        null,
         'http',
         'routes',
         new Map([
@@ -71,8 +73,8 @@ describe('PathToRegexRouter', () => {
           ],
         ])
       )
-      pikkuState('http', 'middleware', new Map())
-      pikkuState('channel', 'channels', new Map())
+      pikkuState(null, 'http', 'middleware', new Map())
+      pikkuState(null, 'channel', 'channels', new Map())
 
       router.initialize()
 
@@ -98,6 +100,7 @@ describe('PathToRegexRouter', () => {
     test('should handle multi-parameter routes', () => {
       // Setup routes with multiple parameters
       pikkuState(
+        null,
         'http',
         'routes',
         new Map([
@@ -116,8 +119,8 @@ describe('PathToRegexRouter', () => {
           ],
         ])
       )
-      pikkuState('http', 'middleware', new Map())
-      pikkuState('channel', 'channels', new Map())
+      pikkuState(null, 'http', 'middleware', new Map())
+      pikkuState(null, 'channel', 'channels', new Map())
 
       router.initialize()
 
@@ -139,6 +142,7 @@ describe('PathToRegexRouter', () => {
     test('should prioritize static routes over dynamic routes for performance', () => {
       // Setup mixed routes where static could conflict with dynamic
       pikkuState(
+        null,
         'http',
         'routes',
         new Map([
@@ -151,8 +155,8 @@ describe('PathToRegexRouter', () => {
           ],
         ])
       )
-      pikkuState('http', 'middleware', new Map())
-      pikkuState('channel', 'channels', new Map())
+      pikkuState(null, 'http', 'middleware', new Map())
+      pikkuState(null, 'channel', 'channels', new Map())
 
       router.initialize()
 
@@ -167,6 +171,7 @@ describe('PathToRegexRouter', () => {
   describe('Path Normalization', () => {
     test('should normalize paths without leading slash', () => {
       pikkuState(
+        null,
         'http',
         'routes',
         new Map([
@@ -179,8 +184,8 @@ describe('PathToRegexRouter', () => {
           ],
         ])
       )
-      pikkuState('http', 'middleware', new Map())
-      pikkuState('channel', 'channels', new Map())
+      pikkuState(null, 'http', 'middleware', new Map())
+      pikkuState(null, 'channel', 'channels', new Map())
 
       router.initialize()
 
@@ -201,9 +206,10 @@ describe('PathToRegexRouter', () => {
 
   describe('Channel Routes Integration', () => {
     test('should handle channel routes as GET routes', () => {
-      pikkuState('http', 'routes', new Map())
-      pikkuState('http', 'middleware', new Map())
+      pikkuState(null, 'http', 'routes', new Map())
+      pikkuState(null, 'http', 'middleware', new Map())
       pikkuState(
+        null,
         'channel',
         'channels',
         new Map([
@@ -233,11 +239,13 @@ describe('PathToRegexRouter', () => {
       const routeMiddleware = [async () => {}]
 
       pikkuState(
+        null,
         'http',
         'routes',
         new Map([['get', new Map([['/api/test', mockRoute('/api/test')]])]])
       )
       pikkuState(
+        null,
         'http',
         'middleware',
         new Map([
@@ -245,7 +253,7 @@ describe('PathToRegexRouter', () => {
           ['/api/test', routeMiddleware],
         ])
       )
-      pikkuState('channel', 'channels', new Map())
+      pikkuState(null, 'channel', 'channels', new Map())
 
       router.initialize()
 
@@ -260,12 +268,13 @@ describe('PathToRegexRouter', () => {
   describe('No Match Scenarios', () => {
     test('should return null for non-existent routes', () => {
       pikkuState(
+        null,
         'http',
         'routes',
         new Map([['get', new Map([['/existing', mockRoute('/existing')]])]])
       )
-      pikkuState('http', 'middleware', new Map())
-      pikkuState('channel', 'channels', new Map())
+      pikkuState(null, 'http', 'middleware', new Map())
+      pikkuState(null, 'channel', 'channels', new Map())
 
       router.initialize()
 
@@ -275,12 +284,13 @@ describe('PathToRegexRouter', () => {
 
     test('should return null for unsupported HTTP methods', () => {
       pikkuState(
+        null,
         'http',
         'routes',
         new Map([['get', new Map([['/test', mockRoute('/test')]])]])
       )
-      pikkuState('http', 'middleware', new Map())
-      pikkuState('channel', 'channels', new Map())
+      pikkuState(null, 'http', 'middleware', new Map())
+      pikkuState(null, 'channel', 'channels', new Map())
 
       router.initialize()
 
@@ -292,12 +302,13 @@ describe('PathToRegexRouter', () => {
   describe('Lazy Initialization', () => {
     test('should initialize automatically on first match call', () => {
       pikkuState(
+        null,
         'http',
         'routes',
         new Map([['get', new Map([['/test', mockRoute('/test')]])]])
       )
-      pikkuState('http', 'middleware', new Map())
-      pikkuState('channel', 'channels', new Map())
+      pikkuState(null, 'http', 'middleware', new Map())
+      pikkuState(null, 'channel', 'channels', new Map())
 
       // Don't call initialize manually
       const result = router.match('get', '/test')

package/src/wirings/http/routers/path-to-regex.ts

@@ -25,8 +25,8 @@ export class PathToRegexRouter implements Router {
   }
 
   public initialize() {
-    const routes = pikkuState('http', 'routes')
-    const channelRoutes = pikkuState('channel', 'channels')
+    const routes = pikkuState(null, 'http', 'routes')
+    const channelRoutes = pikkuState(null, 'channel', 'channels')
 
     // Helper function to compile routes for a given method
     const compileRoutesForMethod = (

package/src/wirings/mcp/index.ts

@@ -1,3 +1,27 @@
-export * from './mcp.types.js'
-export * from './mcp-runner.js'
-export * from './mcp-endpoint-registry.js'
+export { MCPEndpointRegistry } from './mcp-endpoint-registry.js'
+export {
+  MCPError,
+  wireMCPResource,
+  wireMCPPrompt,
+  runMCPResource,
+  runMCPTool,
+  runMCPPrompt,
+} from './mcp-runner.js'
+export {
+  getMCPResourcesMeta,
+  getMCPToolsMeta,
+  getMCPPromptsMeta,
+} from './mcp-runner.js'
+export type {
+  AssertMCPResourceURIParams,
+  CoreMCPPrompt,
+  CoreMCPResource,
+  CoreMCPTool,
+  MCPPromptResponse,
+  MCPResourceMeta,
+  MCPResourceResponse,
+  MCPToolMeta,
+  MCPToolResponse,
+  MCPPromptMeta,
+  PikkuMCP,
+} from './mcp.types.js'

package/src/wirings/mcp/mcp-endpoint-registry.test.ts

@@ -147,7 +147,7 @@ describe('MCPEndpointRegistry', () => {
           uri: 'file://test.txt',
           title: 'Test Resource',
           description: 'Test description',
-          pikkuFuncName: 'testResource',
+          pikkuFuncId: 'testResource',
           inputSchema: null,
           outputSchema: null,
           mimeType: 'text/plain',
@@ -164,7 +164,7 @@ describe('MCPEndpointRegistry', () => {
           name: 'test-tool',
           title: 'Test Tool',
           description: 'Test description',
-          pikkuFuncName: 'testTool',
+          pikkuFuncId: 'testTool',
           inputSchema: null,
           outputSchema: null,
         },
@@ -179,7 +179,7 @@ describe('MCPEndpointRegistry', () => {
         'test-prompt': {
           name: 'test-prompt',
           description: 'Test Prompt',
-          pikkuFuncName: 'testPrompt',
+          pikkuFuncId: 'testPrompt',
           inputSchema: null,
           outputSchema: null,
           arguments: [],

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

@@ -7,7 +7,6 @@ import {
 } from '../../types/core.types.js'
 import type {
   CoreMCPResource,
-  CoreMCPTool,
   CoreMCPPrompt,
   JsonRpcRequest,
   JsonRpcResponse,
@@ -22,8 +21,15 @@ import { getErrorResponse } from '../../errors/error-handler.js'
 import { closeWireServices } from '../../utils.js'
 import { pikkuState } from '../../pikku-state.js'
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js'
-import { BadRequestError, NotFoundError } from '../../errors/errors.js'
-import { PikkuSessionService } from '../../services/user-session-service.js'
+import {
+  BadRequestError,
+  NotFoundError,
+  PikkuMissingMetaError,
+} from '../../errors/errors.js'
+import {
+  PikkuSessionService,
+  createMiddlewareSessionWireProps,
+} from '../../services/user-session-service.js'
 
 export class MCPError extends Error {
   constructor(public readonly error: JsonRpcErrorResponse) {
@@ -56,39 +62,21 @@ export const wireMCPResource = <
 >(
   mcpResource: CoreMCPResource<PikkuFunctionConfig>
 ) => {
-  const resourcesMeta = pikkuState('mcp', 'resourcesMeta')
+  const resourcesMeta = pikkuState(null, 'mcp', 'resourcesMeta')
   const mcpResourceMeta = resourcesMeta[mcpResource.uri]
   if (!mcpResourceMeta) {
-    throw new Error(`MCP resource metadata not found for '${mcpResource.uri}'`)
+    throw new PikkuMissingMetaError(
+      `Missing generated metadata for MCP resource '${mcpResource.uri}'`
+    )
   }
-  addFunction(mcpResourceMeta.pikkuFuncName, mcpResource.func as any)
-  const resources = pikkuState('mcp', 'resources')
+  addFunction(mcpResourceMeta.pikkuFuncId, mcpResource.func as any)
+  const resources = pikkuState(null, 'mcp', 'resources')
   if (resources.has(mcpResource.uri)) {
     throw new Error(`MCP resource already exists: ${mcpResource.uri}`)
   }
   resources.set(mcpResource.uri, mcpResource)
 }
 
-export const wireMCPTool = <
-  PikkuFunctionConfig extends CorePikkuFunctionConfig<
-    CorePikkuFunctionSessionless<any, any>
-  > = CorePikkuFunctionConfig<CorePikkuFunctionSessionless<any, any>>,
->(
-  mcpTool: CoreMCPTool<PikkuFunctionConfig>
-) => {
-  const toolsMeta = pikkuState('mcp', 'toolsMeta')
-  const mcpToolMeta = toolsMeta[mcpTool.name]
-  if (!mcpToolMeta) {
-    throw new Error(`MCP tool metadata not found for '${mcpTool.name}'`)
-  }
-  addFunction(mcpToolMeta.pikkuFuncName, mcpTool.func as any)
-  const tools = pikkuState('mcp', 'tools')
-  if (tools.has(mcpTool.name)) {
-    throw new Error(`MCP tool already exists: ${mcpTool.name}`)
-  }
-  tools.set(mcpTool.name, mcpTool)
-}
-
 export const wireMCPPrompt = <
   PikkuFunctionConfig extends CorePikkuFunctionConfig<
     CorePikkuFunctionSessionless<any, any>
@@ -96,13 +84,15 @@ export const wireMCPPrompt = <
 >(
   mcpPrompt: CoreMCPPrompt<PikkuFunctionConfig>
 ) => {
-  const promptsMeta = pikkuState('mcp', 'promptsMeta')
+  const promptsMeta = pikkuState(null, 'mcp', 'promptsMeta')
   const mcpPromptMeta = promptsMeta[mcpPrompt.name]
   if (!mcpPromptMeta) {
-    throw new Error(`MCP prompt metadata not found for '${mcpPrompt.name}'`)
+    throw new PikkuMissingMetaError(
+      `Missing generated metadata for MCP prompt '${mcpPrompt.name}'`
+    )
   }
-  addFunction(mcpPromptMeta.pikkuFuncName, mcpPrompt.func as any)
-  const prompts = pikkuState('mcp', 'prompts')
+  addFunction(mcpPromptMeta.pikkuFuncId, mcpPrompt.func as any)
+  const prompts = pikkuState(null, 'mcp', 'prompts')
   if (prompts.has(mcpPrompt.name)) {
     throw new Error(`MCP prompt already exists: ${mcpPrompt.name}`)
   }
@@ -115,15 +105,15 @@ export async function runMCPResource(
   uri: string
 ) {
   let endpoint: CoreMCPResource | undefined
-  let pikkuFuncName: string | undefined
+  let pikkuFuncId: string | undefined
   let extractedParams: Record<string, string> = {}
 
-  const metas = pikkuState('mcp', 'resourcesMeta')
-  const endpoints = pikkuState('mcp', 'resources')
+  const metas = pikkuState(null, 'mcp', 'resourcesMeta')
+  const endpoints = pikkuState(null, 'mcp', 'resources')
 
   if (endpoints.has(uri)) {
     endpoint = endpoints.get(uri)
-    pikkuFuncName = metas[uri]?.pikkuFuncName
+    pikkuFuncId = metas[uri]?.pikkuFuncId
   } else {
     for (const [uriTemplate, value] of endpoints.entries()) {
       // Extract parameter names from the template
@@ -139,7 +129,7 @@ export async function runMCPResource(
 
       if (match) {
         endpoint = value
-        pikkuFuncName = metas[uriTemplate]?.pikkuFuncName
+        pikkuFuncId = metas[uriTemplate]?.pikkuFuncId
 
         // Extract parameter values and create params object
         for (let i = 0; i < paramNames.length; i++) {
@@ -158,7 +148,7 @@ export async function runMCPResource(
     'resource',
     uri,
     endpoint,
-    pikkuFuncName,
+    pikkuFuncId,
     { ...params, mcp: { ...params.mcp, uri } } as RunMCPEndpointParams<
       keyof CoreMCPResource
     >
@@ -170,14 +160,13 @@ export async function runMCPTool(
   params: RunMCPEndpointParams,
   name: string
 ) {
-  const endpoint = pikkuState('mcp', 'tools').get(name)
-  const meta = pikkuState('mcp', 'toolsMeta')[name]
+  const meta = pikkuState(null, 'mcp', 'toolsMeta')[name]
   return await runMCPPikkuFunc(
     request,
     'tool',
     name,
-    endpoint,
-    meta?.pikkuFuncName,
+    undefined,
+    meta?.pikkuFuncId,
     params
   )
 }
@@ -187,14 +176,14 @@ export async function runMCPPrompt(
   params: RunMCPEndpointParams,
   name: string
 ) {
-  const endpoint = pikkuState('mcp', 'prompts').get(name)
-  const meta = pikkuState('mcp', 'promptsMeta')[name]
+  const endpoint = pikkuState(null, 'mcp', 'prompts').get(name)
+  const meta = pikkuState(null, 'mcp', 'promptsMeta')[name]
   return await runMCPPikkuFunc(
     request,
     'prompt',
     name,
     endpoint,
-    meta?.pikkuFuncName,
+    meta?.pikkuFuncId,
     params
   )
 }
@@ -206,27 +195,26 @@ async function runMCPPikkuFunc(
   request: JsonRpcRequest,
   type: 'resource' | 'tool' | 'prompt',
   name: string,
-  mcp: CoreMCPResource | CoreMCPTool | CoreMCPPrompt | undefined,
-  pikkuFuncName: string | undefined,
+  mcp: CoreMCPResource | CoreMCPPrompt | undefined,
+  pikkuFuncId: string | undefined,
   { singletonServices, createWireServices, mcp: mcpWire }: RunMCPEndpointParams
 ): Promise<JsonRpcResponse> {
   let wireServices: any
 
   try {
-    // Validate JSON-RPC request structure
     if (request.jsonrpc !== '2.0') {
       throw new BadRequestError(
         'Invalid JSON-RPC version, only supoorted version is 2.0'
       )
     }
 
-    if (!mcp) {
+    if (mcp === undefined && type !== 'tool') {
       throw new NotFoundError(
         `MCP '${type}' registration not found for '${name}'`
       )
     }
 
-    if (!pikkuFuncName) {
+    if (!pikkuFuncId) {
       throw new NotFoundError(
         `MCP '${type}' PikkuFunction Mapping not found for '${name}'`
       )
@@ -234,33 +222,38 @@ async function runMCPPikkuFunc(
 
     singletonServices.logger.debug(`Running MCP ${type}: ${name}`)
 
+    const mcpSessionService = new PikkuSessionService()
     const wire: PikkuWire = {
       mcp: mcpWire,
-      session: new PikkuSessionService(),
+      ...createMiddlewareSessionWireProps(mcpSessionService),
     }
 
-    // Get metadata for the MCP endpoint to access pre-resolved middleware
     let meta: any
     if (type === 'resource') {
-      meta = pikkuState('mcp', 'resourcesMeta')[name]
+      meta = pikkuState(null, 'mcp', 'resourcesMeta')[name]
     } else if (type === 'tool') {
-      meta = pikkuState('mcp', 'toolsMeta')[name]
+      meta = pikkuState(null, 'mcp', 'toolsMeta')[name]
     } else if (type === 'prompt') {
-      meta = pikkuState('mcp', 'promptsMeta')[name]
+      meta = pikkuState(null, 'mcp', 'promptsMeta')[name]
     }
 
-    const result = await runPikkuFunc('mcp', `${type}:${name}`, pikkuFuncName, {
+    let result = await runPikkuFunc('mcp', `${type}:${name}`, pikkuFuncId, {
       singletonServices,
       createWireServices,
       data: () => request.params,
       inheritedMiddleware: meta?.middleware,
-      wireMiddleware: mcp.middleware,
+      wireMiddleware: mcp?.middleware,
       inheritedPermissions: meta?.permissions,
-      wirePermissions: mcp.permissions,
-      tags: mcp.tags,
+      wirePermissions: mcp?.permissions,
+      tags: mcp?.tags,
       wire,
+      sessionService: mcpSessionService,
     })
 
+    if (type === 'tool' && meta?.outputSchema !== 'MCPToolResponse') {
+      result = [{ type: 'text', text: JSON.stringify(result) }]
+    }
+
     return {
       id: request.id,
       result,
@@ -297,26 +290,22 @@ async function runMCPPikkuFunc(
   }
 }
 
-export const getMCPTools = () => {
-  return pikkuState('mcp', 'tools')
-}
-
 export const getMCPResources = () => {
-  return pikkuState('mcp', 'resources')
+  return pikkuState(null, 'mcp', 'resources')
 }
 
 export const getMCPResourcesMeta = () => {
-  return pikkuState('mcp', 'resourcesMeta')
+  return pikkuState(null, 'mcp', 'resourcesMeta')
 }
 
 export const getMCPToolsMeta = () => {
-  return pikkuState('mcp', 'toolsMeta')
+  return pikkuState(null, 'mcp', 'toolsMeta')
 }
 
 export const getMCPPrompts = () => {
-  return pikkuState('mcp', 'prompts')
+  return pikkuState(null, 'mcp', 'prompts')
 }
 
 export const getMCPPromptsMeta = () => {
-  return pikkuState('mcp', 'promptsMeta')
+  return pikkuState(null, 'mcp', 'promptsMeta')
 }

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

@@ -50,7 +50,7 @@ export type PikkuMCP<Tools extends string = any> = {
 export type MCPResourceMeta = Record<
   string,
   Omit<CoreMCPResource, 'func' | 'middleware' | 'permissions'> & {
-    pikkuFuncName: string
+    pikkuFuncId: string
     inputSchema: string | null
     outputSchema: string | null
     middleware?: MiddlewareMetadata[] // Pre-resolved middleware chain (tag + explicit)
@@ -64,7 +64,7 @@ export type MCPResourceMeta = Record<
 export type MCPToolMeta = Record<
   string,
   Omit<CoreMCPTool, 'func' | 'middleware' | 'permissions'> & {
-    pikkuFuncName: string
+    pikkuFuncId: string
     inputSchema: string | null
     outputSchema: string | null
     middleware?: MiddlewareMetadata[] // Pre-resolved middleware chain (tag + explicit)
@@ -78,7 +78,7 @@ export type MCPToolMeta = Record<
 export type MCPPromptMeta = Record<
   string,
   Omit<CoreMCPPrompt, 'func' | 'middleware' | 'permissions'> & {
-    pikkuFuncName: string
+    pikkuFuncId: string
     inputSchema: string | null
     outputSchema: string | null
     arguments: Array<{

package/src/wirings/node/index.ts

@@ -0,0 +1,2 @@
+export type { CoreNodeConfig, NodeType } from './node.types.js'
+export type { NodesMeta } from './node.types.js'

package/src/wirings/node/node.types.ts

@@ -0,0 +1,23 @@
+export type NodeType = 'trigger' | 'action' | 'end'
+
+export type CoreNodeConfig = {
+  displayName: string
+  category: string
+  type: NodeType
+  errorOutput?: boolean
+}
+
+export type NodeMeta = {
+  name: string
+  displayName: string
+  category: string
+  type: NodeType
+  rpc: string
+  description?: string
+  errorOutput: boolean
+  inputSchemaName: string | null
+  outputSchemaName: string | null
+  tags?: string[]
+}
+
+export type NodesMeta = Record<string, NodeMeta>

package/src/wirings/oauth2/index.ts

@@ -0,0 +1,3 @@
+export { OAuth2Client } from './oauth2-client.js'
+export { wireOAuth2Credential } from './wire-oauth2-credential.js'
+export type { OAuth2AppCredential, OAuth2Token } from './oauth2.types.js'