@pikku/core 0.9.11 → 0.10.0

package/src/factory-functions.test.ts

@@ -1,6 +1,11 @@
 import { test } from 'node:test'
 import assert from 'node:assert'
-import { pikkuPermission, pikkuMiddleware } from './index.js'
+import {
+  pikkuPermission,
+  pikkuMiddleware,
+  pikkuPermissionFactory,
+  pikkuMiddlewareFactory,
+} from './index.js'
 
 test('pikkuPermission factory function', async () => {
   const permission = pikkuPermission(async ({ logger }, data, session) => {
@@ -35,3 +40,57 @@ test('pikkuMiddleware returns the same function', async () => {
 
   assert.strictEqual(wrappedFn, originalFn)
 })
+
+test('pikkuPermissionFactory creates a factory function', async () => {
+  const factory = pikkuPermissionFactory<{ role: string }>(({ role }) => {
+    return pikkuPermission(async ({ logger }, data, session) => {
+      return session?.role === role
+    })
+  })
+
+  assert.strictEqual(typeof factory, 'function')
+  assert.strictEqual(factory.length, 1) // input parameter
+
+  // Call the factory to get a permission
+  const permission = factory({ role: 'admin' })
+  assert.strictEqual(typeof permission, 'function')
+  assert.strictEqual(permission.length, 3) // services, data, session
+})
+
+test('pikkuMiddlewareFactory creates a factory function', async () => {
+  const factory = pikkuMiddlewareFactory<{ message: string }>(({ message }) => {
+    return pikkuMiddleware(async ({ logger }, interactions, next) => {
+      logger.info(message)
+      await next()
+    })
+  })
+
+  assert.strictEqual(typeof factory, 'function')
+  assert.strictEqual(factory.length, 1) // input parameter
+
+  // Call the factory to get middleware
+  const middleware = factory({ message: 'test' })
+  assert.strictEqual(typeof middleware, 'function')
+  assert.strictEqual(middleware.length, 3) // services, interactions, next
+})
+
+test('pikkuPermissionFactory returns the same factory', async () => {
+  const originalFactory = ({ role }) =>
+    pikkuPermission(async ({ logger }, data, session) => {
+      return session?.role === role
+    })
+  const wrappedFactory = pikkuPermissionFactory(originalFactory)
+
+  assert.strictEqual(wrappedFactory, originalFactory)
+})
+
+test('pikkuMiddlewareFactory returns the same factory', async () => {
+  const originalFactory = ({ message }) =>
+    pikkuMiddleware(async ({ logger }, interactions, next) => {
+      logger.info(message)
+      await next()
+    })
+  const wrappedFactory = pikkuMiddlewareFactory(originalFactory)
+
+  assert.strictEqual(wrappedFactory, originalFactory)
+})

package/src/function/function-runner.test.ts

@@ -17,14 +17,24 @@ beforeEach(() => {
 // Helper function to add function with metadata for tests
 const addTestFunction = (funcName: string, funcConfig: any) => {
   addFunction(funcName, funcConfig)
+  // Convert tags to middleware metadata
+  const middleware = funcConfig.tags
+    ? funcConfig.tags.map((tag: string) => ({ type: 'tag' as const, tag }))
+    : undefined
+  // Convert tags to permissions metadata
+  const permissions = funcConfig.tags
+    ? funcConfig.tags.map((tag: string) => ({ type: 'tag' as const, tag }))
+    : undefined
   pikkuState('function', 'meta')[funcName] = {
     pikkuFuncName: funcName,
     inputSchemaName: null,
     outputSchemaName: null,
+    middleware,
+    permissions,
   }
 }
 
-const mockServices: CoreServices = {
+const mockSingletonServices = {
   logger: {
     info: () => {},
     warn: () => {},
@@ -33,8 +43,12 @@ const mockServices: CoreServices = {
   },
 } as any
 
+const mockServices: CoreServices = {
+  ...mockSingletonServices,
+} as any
+
 describe('runPikkuFunc - Integration Tests', () => {
-  test('should execute middleware in correct order: wiringTags → wiringMiddleware → funcMiddleware → funcTags', async () => {
+  test('should execute middleware in correct order: wiringTags → wiringMiddleware → funcTags → funcMiddleware', async () => {
     const executionOrder: string[] = []
     const createMiddleware = (name: string): CorePikkuMiddleware => {
       return async (services, interaction, next) => {
@@ -61,20 +75,23 @@ describe('runPikkuFunc - Integration Tests', () => {
       Math.random().toString(),
       'testFunc',
       {
+        singletonServices: mockSingletonServices,
         getAllServices: () => mockServices,
-        data: {},
-        middleware: [createMiddleware('wiringMiddleware')],
-        tags: ['wiringTag'],
+        data: () => ({}),
+        wireMiddleware: [createMiddleware('wiringMiddleware')],
+        inheritedMiddleware: [{ type: 'tag', tag: 'wiringTag' }],
+        auth: false,
+        interaction: {},
       }
     )
 
     assert.equal(result, 'success')
-    // Order: wiringTags, wiringMiddleware, funcMiddleware, funcTags
+    // Order: wireInheritedMiddleware (tags), wireMiddleware, funcInheritedMiddleware (tags), funcMiddleware
     assert.deepEqual(executionOrder, [
       'wiringTag',
       'wiringMiddleware',
-      'funcMiddleware',
       'funcTag',
+      'funcMiddleware',
       'main',
     ])
   })
@@ -128,10 +145,13 @@ describe('runPikkuFunc - Integration Tests', () => {
       Math.random().toString(),
       'testFunc',
       {
+        singletonServices: mockSingletonServices,
         getAllServices: () => mockServices,
-        data: {},
-        permissions: wiringPermissions,
+        data: () => ({}),
+        wirePermissions: wiringPermissions,
         tags: ['wiringTag'],
+        auth: false,
+        interaction: {},
       }
     )
 
@@ -157,9 +177,12 @@ describe('runPikkuFunc - Integration Tests', () => {
 
     await assert.rejects(
       runPikkuFunc(PikkuWiringTypes.rpc, Math.random().toString(), 'testFunc', {
+        singletonServices: mockSingletonServices,
         getAllServices: () => mockServices,
-        data: {},
+        data: () => ({}),
         tags: ['wiringTag'],
+        auth: false,
+        interaction: {},
       }),
       {
         message: 'Permission denied',
@@ -178,9 +201,12 @@ describe('runPikkuFunc - Integration Tests', () => {
 
     await assert.rejects(
       runPikkuFunc(PikkuWiringTypes.rpc, Math.random().toString(), 'testFunc', {
+        singletonServices: mockSingletonServices,
         getAllServices: () => mockServices,
-        data: {},
-        permissions: wiringPermissions,
+        data: () => ({}),
+        wirePermissions: wiringPermissions,
+        auth: false,
+        interaction: {},
       }),
       {
         message: 'Permission denied',
@@ -200,8 +226,11 @@ describe('runPikkuFunc - Integration Tests', () => {
 
     await assert.rejects(
       runPikkuFunc(PikkuWiringTypes.rpc, Math.random().toString(), 'testFunc', {
+        singletonServices: mockSingletonServices,
         getAllServices: () => mockServices,
-        data: {},
+        data: () => ({}),
+        auth: false,
+        interaction: {},
       }),
       {
         message: 'Permission denied',
@@ -221,8 +250,11 @@ describe('runPikkuFunc - Integration Tests', () => {
 
     await assert.rejects(
       runPikkuFunc(PikkuWiringTypes.rpc, Math.random().toString(), 'testFunc', {
+        singletonServices: mockSingletonServices,
         getAllServices: () => mockServices,
-        data: {},
+        data: () => ({}),
+        auth: false,
+        interaction: {},
       }),
       {
         message: 'Permission denied',
@@ -256,8 +288,11 @@ describe('runPikkuFunc - Integration Tests', () => {
       Math.random().toString(),
       'testFunc',
       {
+        singletonServices: mockSingletonServices,
         getAllServices: () => mockServices,
-        data: {},
+        data: () => ({}),
+        auth: false,
+        interaction: {},
       }
     )
 
@@ -305,8 +340,11 @@ describe('runPikkuFunc - Integration Tests', () => {
       Math.random().toString(),
       'testFunc',
       {
+        singletonServices: mockSingletonServices,
         getAllServices: () => mockServices,
-        data: {},
+        data: () => ({}),
+        auth: false,
+        interaction: {},
       }
     )
 
@@ -330,8 +368,11 @@ describe('runPikkuFunc - Integration Tests', () => {
       Math.random().toString(),
       'simpleFunc',
       {
+        singletonServices: mockSingletonServices,
         getAllServices: () => mockServices,
-        data: {},
+        data: () => ({}),
+        auth: false,
+        interaction: {},
       }
     )
 
@@ -371,17 +412,21 @@ describe('runPikkuFunc - Integration Tests', () => {
       Math.random().toString(),
       'testFunc',
       {
+        singletonServices: mockSingletonServices,
         getAllServices: () => mockServices,
-        data: {},
-        middleware: [wiringMiddleware],
-        permissions: wiringPermissions,
+        data: () => ({}),
+        wireMiddleware: [wiringMiddleware],
+        wirePermissions: wiringPermissions,
+        auth: false,
+        interaction: {},
       }
     )
 
     assert.equal(result, 'success')
+    // Permissions run after middleware (middleware can set/modify session)
     assert.deepEqual(executionOrder, [
-      'wiringPermission',
       'wiringMiddleware',
+      'wiringPermission',
       'main',
     ])
   })
@@ -421,15 +466,19 @@ describe('runPikkuFunc - Integration Tests', () => {
       Math.random().toString(),
       'testFunc',
       {
+        singletonServices: mockSingletonServices,
         getAllServices: () => mockServices,
-        data: {},
+        data: () => ({}),
+        auth: false,
+        interaction: {},
       }
     )
 
     assert.equal(result, 'success')
+    // Permissions run after middleware (middleware can set/modify session)
     assert.deepEqual(executionOrder, [
-      'funcPermission',
       'funcMiddleware',
+      'funcPermission',
       'main',
     ])
   })
@@ -456,9 +505,12 @@ describe('runPikkuFunc - Integration Tests', () => {
       Math.random().toString(),
       'testFunc',
       {
+        singletonServices: mockSingletonServices,
         getAllServices: () => mockServices,
-        data: testData,
-        session: testSession,
+        data: () => testData,
+        userSession: { get: () => testSession, set: () => {} } as any,
+        auth: false,
+        interaction: {},
       }
     )
 
@@ -488,8 +540,11 @@ describe('runPikkuFunc - Integration Tests', () => {
       Math.random().toString(),
       'testFunc',
       {
+        singletonServices: mockSingletonServices,
         getAllServices: asyncGetServices,
-        data: {},
+        data: () => ({}),
+        auth: false,
+        interaction: {},
       }
     )
 

package/src/function/function-runner.ts

@@ -1,4 +1,3 @@
-import { ForbiddenError } from '../errors/errors.js'
 import { runMiddleware, combineMiddleware } from '../middleware-runner.js'
 import { runPermissions } from '../permissions.js'
 import { pikkuState } from '../pikku-state.js'
@@ -8,24 +7,23 @@ import {
   CoreUserSession,
   CorePikkuMiddleware,
   PikkuWiringTypes,
+  CoreSingletonServices,
+  PikkuInteraction,
+  MiddlewareMetadata,
+  PermissionMetadata,
 } from '../types/core.types.js'
 import {
   CorePermissionGroup,
-  CorePikkuFunction,
   CorePikkuFunctionConfig,
-  CorePikkuFunctionSessionless,
+  CorePikkuPermission,
 } from './functions.types.js'
+import { UserSessionService } from '../services/user-session-service.js'
+import { ForbiddenError } from '../errors/errors.js'
 
 export const addFunction = (
   funcName: string,
-  funcConfig:
-    | CorePikkuFunctionConfig<any, any>
-    | CorePikkuFunctionSessionless<any, any>
-    | CorePikkuFunction<any, any>
+  funcConfig: CorePikkuFunctionConfig<any, any>
 ) => {
-  if (funcConfig instanceof Function) {
-    funcConfig = { func: funcConfig }
-  }
   pikkuState('function', 'functions').set(funcName, funcConfig)
 }
 
@@ -48,20 +46,32 @@ export const runPikkuFunc = async <In = any, Out = any>(
   funcName: string,
   {
     getAllServices,
+    singletonServices,
     data,
-    session,
-    permissions: wiringPermissions,
-    middleware: wiringMiddleware,
+    userSession,
+    auth: wiringAuth,
+    inheritedMiddleware,
+    wireMiddleware,
+    inheritedPermissions,
+    wirePermissions,
     coerceDataFromSchema,
     tags = [],
+    interaction,
   }: {
-    getAllServices: () => Promise<CoreServices> | CoreServices
-    data: In
-    session?: CoreUserSession
-    permissions?: CorePermissionGroup
-    middleware?: CorePikkuMiddleware[]
+    singletonServices: CoreSingletonServices
+    getAllServices: (
+      session?: CoreUserSession
+    ) => Promise<CoreServices> | CoreServices
+    userSession?: UserSessionService<CoreUserSession>
+    data: () => Promise<In> | In
+    auth?: boolean
+    inheritedMiddleware?: MiddlewareMetadata[]
+    wireMiddleware?: CorePikkuMiddleware[]
+    inheritedPermissions?: PermissionMetadata[]
+    wirePermissions?: CorePermissionGroup | CorePikkuPermission[]
     coerceDataFromSchema?: boolean
     tags?: string[]
+    interaction: PikkuInteraction
   }
 ): Promise<Out> => {
   const funcConfig = pikkuState('function', 'functions').get(funcName)
@@ -73,60 +83,82 @@ export const runPikkuFunc = async <In = any, Out = any>(
     throw new Error(`Function meta not found: ${funcName}`)
   }
 
-  if (funcConfig.auth && !session) {
-    throw new ForbiddenError(
-      `Function ${funcName} requires authentication even though transport does not`
-    )
-  }
+  // Convert tags to PermissionMetadata and merge with inheritedPermissions
+  const mergedInheritedPermissions: PermissionMetadata[] = [
+    ...(inheritedPermissions || []),
+    ...(tags?.map((tag) => ({ type: 'tag' as const, tag })) || []),
+  ]
 
-  const allServices = await getAllServices()
+  // Helper function to run permissions and execute the function
+  const executeFunction = async () => {
+    const session = userSession?.get()
+    if (wiringAuth === true || funcConfig.auth === true) {
+      // This means it was explicitly enabled in either wiring or function and has to be respected
+      if (!session) {
+        throw new ForbiddenError('Authentication required')
+      }
+    }
+    if (wiringAuth === undefined && funcConfig.auth === undefined) {
+      // We always default to requiring auth unless explicitly disabled
+      if (!session) {
+        throw new ForbiddenError('Authentication required')
+      }
+    }
 
-  const inputSchemaName = funcMeta.inputSchemaName
-  if (inputSchemaName) {
-    // Validate request data against the defined schema, if any
-    await validateSchema(
-      allServices.logger,
-      allServices.schema,
-      inputSchemaName,
-      data
-    )
-    // Coerce (top level) query string parameters or date objects if specified by the schema
-    if (coerceDataFromSchema) {
-      coerceTopLevelDataFromSchema(inputSchemaName, data)
+    // Evaluate the data from the lazy function
+    const actualData = await data()
+
+    // Validate and coerce data if schema is defined
+    const inputSchemaName = funcMeta.inputSchemaName
+    if (inputSchemaName) {
+      // Validate request data against the defined schema, if any
+      await validateSchema(
+        singletonServices.logger,
+        singletonServices.schema,
+        inputSchemaName,
+        actualData
+      )
+      // Coerce (top level) query string parameters or date objects if specified by the schema
+      if (coerceDataFromSchema) {
+        coerceTopLevelDataFromSchema(inputSchemaName, actualData)
+      }
     }
-  }
 
-  // Run permission checks in the specified order
-  await runPermissions(wireType, wireId, {
-    wiringTags: tags,
-    wiringPermissions,
-    funcTags: funcConfig.tags,
-    funcPermissions: funcConfig.permissions,
-    allServices,
-    data,
-    session,
-  })
+    const allServices = await getAllServices(session)
+
+    // Run permissions check with combined permissions: inheritedPermissions (including tags) → wirePermissions → funcPermissions
+    await runPermissions(wireType, wireId, {
+      wireInheritedPermissions: mergedInheritedPermissions,
+      wirePermissions: wirePermissions,
+      funcInheritedPermissions: funcMeta.permissions,
+      funcPermissions: funcConfig.permissions,
+      allServices,
+      data: actualData,
+      session,
+    })
 
-  // Combine all middleware: wiring tags → wiring middleware → func middleware → func tags
+    return await funcConfig.func(allServices, actualData, session!)
+  }
+
+  // Combine all middleware: inheritedMiddleware → wireMiddleware → funcMiddleware
   const allMiddleware = combineMiddleware(wireType, wireId, {
-    wiringTags: tags,
-    wiringMiddleware,
+    wireInheritedMiddleware: inheritedMiddleware,
+    wireMiddleware,
+    funcInheritedMiddleware: funcMeta.middleware,
     funcMiddleware: funcConfig.middleware,
-    funcTags: funcConfig.tags,
   })
 
   if (allMiddleware.length > 0) {
     return (await runMiddleware<CorePikkuMiddleware>(
-      allServices,
       {
-        http: allServices.http,
-        mcp: allServices.mcp,
-        rpc: allServices.rpc,
+        ...singletonServices,
+        userSession,
       },
+      interaction,
       allMiddleware,
-      async () => await funcConfig.func(allServices, data, session!)
+      executeFunction
     )) as Out
   }
 
-  return (await funcConfig.func(allServices, data, session!)) as Out
+  return (await executeFunction()) as Out
 }

package/src/function/functions.types.ts

@@ -12,6 +12,7 @@ import type {
  *
  * @template In - The input type.
  * @template Out - The output type.
+ * @template ChannelData - The channel data type.
  * @template Services - The services type, defaults to `CoreServices`.
  * @template Session - The session type, defaults to `CoreUserSession`.
  */
@@ -39,6 +40,7 @@ export type CorePikkuFunction<
  *
  * @template In - The input type.
  * @template Out - The output type.
+ * @template ChannelData - The channel data type.
  * @template Services - The services type, defaults to `CoreServices`.
  * @template Session - The session type, defaults to `CoreUserSession`.
  */
@@ -74,17 +76,98 @@ export type CorePikkuPermission<
   Session extends CoreUserSession = CoreUserSession,
 > = (services: Services, data: In, session?: Session) => Promise<boolean>
 
+/**
+ * Configuration object for creating a permission with metadata
+ *
+ * @template In - The input type.
+ * @template Services - The services type, defaults to `CoreServices`.
+ * @template Session - The session type, defaults to `CoreUserSession`.
+ */
+export type CorePikkuPermissionConfig<
+  In = any,
+  Services extends CoreSingletonServices = CoreServices,
+  Session extends CoreUserSession = CoreUserSession,
+> = {
+  /** The permission function */
+  func: CorePikkuPermission<In, Services, Session>
+  /** Optional human-readable name for the permission */
+  name?: string
+  /** Optional description of what the permission checks */
+  description?: string
+}
+
 /**
  * Factory function for creating permissions with tree-shaking support
+ * Supports both direct function and configuration object syntax
+ *
+ * @example
+ * ```typescript
+ * // Direct function syntax
+ * export const adminPermission = pikkuPermission(
+ *   async ({ logger }, data, session) => {
+ *     return session?.role === 'admin'
+ *   }
+ * )
+ *
+ * // Configuration object syntax with metadata
+ * export const adminPermission = pikkuPermission({
+ *   name: 'Admin Permission',
+ *   description: 'Checks if user has admin role',
+ *   func: async ({ logger }, data, session) => {
+ *     return session?.role === 'admin'
+ *   }
+ * })
+ * ```
  */
 export const pikkuPermission = <
   In = any,
   Services extends CoreSingletonServices = CoreServices,
   Session extends CoreUserSession = CoreUserSession,
 >(
-  permission: CorePikkuPermission<In, Services, Session>
+  permission:
+    | CorePikkuPermission<In, Services, Session>
+    | CorePikkuPermissionConfig<In, Services, Session>
 ): CorePikkuPermission<In, Services, Session> => {
-  return permission
+  return typeof permission === 'function' ? permission : permission.func
+}
+
+/**
+ * A factory function that takes input and returns a permission
+ * Used when permissions need configuration/input parameters
+ *
+ * @template In - The input type for the factory.
+ * @template Services - The services type, defaults to `CoreServices`.
+ * @template Session - The session type, defaults to `CoreUserSession`.
+ */
+export type CorePikkuPermissionFactory<
+  In = any,
+  Services extends CoreSingletonServices = CoreServices,
+  Session extends CoreUserSession = CoreUserSession,
+> = (input: In) => CorePikkuPermission<any, Services, Session>
+
+/**
+ * Factory function for creating permission factories
+ * Use this when your permission needs configuration/input parameters
+ *
+ * @example
+ * ```typescript
+ * export const requireRole = pikkuPermissionFactory<{ role: string }>(({
+ *   role
+ * }) => {
+ *   return pikkuPermission(async ({ logger }, data, session) => {
+ *     if (!session || session.role !== role) {
+ *       logger.warn(`Permission denied: required role '${role}'`)
+ *       return false
+ *     }
+ *     return true
+ *   })
+ * })
+ * ```
+ */
+export const pikkuPermissionFactory = <In = any>(
+  factory: CorePikkuPermissionFactory<In>
+): CorePikkuPermissionFactory<In> => {
+  return factory
 }
 
 export type CorePermissionGroup<PikkuPermission = CorePikkuPermission<any>> =

package/src/index.ts

@@ -16,28 +16,15 @@ export * from './wirings/scheduler/index.js'
 export * from './wirings/rpc/index.js'
 export * from './wirings/queue/index.js'
 export * from './wirings/mcp/index.js'
+export * from './wirings/cli/index.js'
 export * from './errors/index.js'
 export * from './middleware/index.js'
 export * from './utils.js'
 export * from './time-utils.js'
 export { pikkuState } from './pikku-state.js'
-export { addMiddleware, runMiddleware } from './middleware-runner.js'
-export { addPermission } from './permissions.js'
-export { wireHTTP, addHTTPMiddleware } from './wirings/http/http-runner.js'
-export { wireChannel } from './wirings/channel/channel-runner.js'
-export { wireScheduler } from './wirings/scheduler/scheduler-runner.js'
-export { wireQueueWorker } from './wirings/queue/queue-runner.js'
 export {
-  wireMCPResource,
-  wireMCPTool,
-  wireMCPPrompt,
-  runMCPResource,
-  runMCPTool,
-  runMCPPrompt,
-  getMCPTools,
-  getMCPResources,
-  getMCPPrompts,
-  getMCPResourcesMeta,
-  getMCPToolsMeta,
-  getMCPPromptsMeta,
-} from './wirings/mcp/mcp-runner.js'
+  runMiddleware,
+  addMiddleware,
+  getMiddlewareByName,
+} from './middleware-runner.js'
+export { addPermission } from './permissions.js'