@pikku/core 0.11.1 → 0.12.0

package/src/factory-functions.test.ts

@@ -1,6 +1,7 @@
 import { test } from 'node:test'
 import assert from 'node:assert'
 import {
+  pikkuAuth,
   pikkuPermission,
   pikkuMiddleware,
   pikkuPermissionFactory,
@@ -21,8 +22,8 @@ test('pikkuMiddleware returns the same function', async () => {
 
 test('pikkuPermissionFactory creates a factory function', async () => {
   const factory = pikkuPermissionFactory<{ role: string }>(({ role }) => {
-    return pikkuPermission(async ({ logger }, data, { initialSession }) => {
-      return (initialSession as any)?.role === role
+    return pikkuPermission(async ({ logger }, data, { session }) => {
+      return (session as any)?.role === role
     })
   })
 
@@ -67,3 +68,42 @@ test('pikkuMiddlewareFactory returns the same factory', async () => {
   const wrappedFactory = pikkuMiddlewareFactory(originalFactory)
   assert.strictEqual(wrappedFactory, originalFactory)
 })
+
+test('pikkuAuth returns a 3-arg wrapper function', async () => {
+  const authFn = async (_services, session) => !!session
+  const wrapped = pikkuAuth(authFn)
+  assert.strictEqual(typeof wrapped, 'function')
+  assert.strictEqual(wrapped.length, 3)
+})
+
+test('pikkuAuth wrapper extracts session from wire and calls auth function', async () => {
+  let receivedSession = null
+  const authFn = async (_services, session) => {
+    receivedSession = session
+    return session.role === 'admin'
+  }
+  const wrapped = pikkuAuth(authFn)
+  const result = await wrapped({}, null, { session: { role: 'admin' } })
+  assert.strictEqual(result, true)
+  assert.deepStrictEqual(receivedSession, { role: 'admin' })
+})
+
+test('pikkuAuth wrapper returns false when no session', async () => {
+  const authFn = async (_services, session) => !!session
+  const wrapped = pikkuAuth(authFn)
+  const result = await wrapped({}, null, { session: null })
+  assert.strictEqual(result, false)
+})
+
+test('pikkuAuth config object syntax works', async () => {
+  const authFn = async (_services, session) => !!session
+  const wrapped = pikkuAuth({
+    func: authFn,
+    name: 'Is Authenticated',
+    description: 'Checks if user has a session',
+  })
+  assert.strictEqual(typeof wrapped, 'function')
+  assert.strictEqual(wrapped.length, 3)
+  const result = await wrapped({}, null, { session: { id: '1' } })
+  assert.strictEqual(result, true)
+})

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

@@ -21,8 +21,8 @@ const addTestFunction = (funcName: string, funcConfig: any) => {
   const permissions = funcConfig.tags
     ? funcConfig.tags.map((tag: string) => ({ type: 'tag' as const, tag }))
     : undefined
-  pikkuState('function', 'meta')[funcName] = {
-    pikkuFuncName: funcName,
+  pikkuState(null, 'function', 'meta')[funcName] = {
+    pikkuFuncId: funcName,
     inputSchemaName: null,
     outputSchemaName: null,
     middleware,
@@ -152,14 +152,8 @@ describe('runPikkuFunc - Integration Tests', () => {
     )
 
     assert.equal(result, 'success')
-    // Order: wiringTags → wiringPermissions → funcTags → funcPermissions
-    assert.deepEqual(executionOrder, [
-      'wiringTag',
-      'wiringPermission',
-      'funcTag',
-      'funcPermission',
-      'main',
-    ])
+    // Order: wiringTags → main (short-circuit on first passing group)
+    assert.deepEqual(executionOrder, ['wiringTag', 'main'])
   })
 
   test('should throw specific error for wiring tag permission failures', async () => {
@@ -340,11 +334,10 @@ describe('runPikkuFunc - Integration Tests', () => {
     )
 
     assert.equal(result, 'success')
-    // Should execute tag permissions first, then function permissions
+    // Should execute tag permissions and short-circuit before function permissions
     assert.deepEqual(executionOrder, [
       'arrayPermission1',
       'arrayPermission2',
-      'objectPermission',
       'main',
     ])
   })

package/src/function/function-runner.ts

@@ -1,4 +1,8 @@
 import { runMiddleware, combineMiddleware } from '../middleware-runner.js'
+import {
+  combineChannelMiddleware,
+  wrapChannelWithMiddleware,
+} from '../wirings/channel/channel-middleware-runner.js'
 import { runPermissions } from '../permissions.js'
 import { pikkuState } from '../pikku-state.js'
 import { coerceTopLevelDataFromSchema, validateSchema } from '../schema.js'
@@ -12,22 +16,96 @@ import {
   PermissionMetadata,
   CoreSingletonServices,
   CreateWireServices,
+  CoreConfig,
 } from '../types/core.types.js'
+import type { CorePikkuChannelMiddleware } from '../wirings/channel/channel.types.js'
 import {
   CorePermissionGroup,
   CorePikkuFunctionConfig,
   CorePikkuPermission,
 } from './functions.types.js'
-import { SessionService } from '../services/user-session-service.js'
+import { parseVersionedId } from '../version.js'
+import {
+  SessionService,
+  createFunctionSessionWireProps,
+} from '../services/user-session-service.js'
 import { ForbiddenError } from '../errors/errors.js'
 import { rpcService } from '../wirings/rpc/rpc-runner.js'
 import { closeWireServices } from '../utils.js'
 
+/**
+ * Get or create singleton services for an external package.
+ * Services are cached in pikkuState to avoid recreation on each call.
+ *
+ * @param packageName - The external package name
+ * @param parentServices - The parent/caller's singleton services (used as base)
+ * @returns The package's singleton services
+ */
+const getOrCreatePackageSingletonServices = async (
+  packageName: string,
+  parentServices: CoreSingletonServices
+): Promise<CoreSingletonServices> => {
+  // Check if we already have cached singleton services for this package
+  const cachedServices = pikkuState(packageName, 'package', 'singletonServices')
+  if (cachedServices) {
+    return cachedServices
+  }
+
+  // Get the package's service factories
+  const factories = pikkuState(packageName, 'package', 'factories')
+  if (!factories || !factories.createSingletonServices) {
+    // No factories registered, use parent services
+    return parentServices
+  }
+
+  // Create config for the package (use parent config if no factory)
+  let config: CoreConfig = parentServices.config
+  if (factories.createConfig) {
+    config = await factories.createConfig(parentServices.variables)
+  }
+
+  // Create singleton services for the package, passing parent services as existing
+  const packageServices = await factories.createSingletonServices(
+    config,
+    parentServices
+  )
+
+  // Cache the services
+  pikkuState(packageName, 'package', 'singletonServices', packageServices)
+
+  return packageServices
+}
+
 export const addFunction = (
   funcName: string,
-  funcConfig: CorePikkuFunctionConfig<any, any>
+  funcConfig: CorePikkuFunctionConfig<any, any>,
+  packageName: string | null = null
 ) => {
-  pikkuState('function', 'functions').set(funcName, funcConfig)
+  pikkuState(packageName, 'function', 'functions').set(funcName, funcConfig)
+}
+
+export const getFunctionNames = (
+  packageName: string | null = null
+): string[] => {
+  const functionsMeta = pikkuState(packageName, 'function', 'meta')
+  return Object.keys(functionsMeta)
+}
+
+export const getAllFunctionNames = (): string[] => {
+  const functions: string[] = []
+
+  const mainFunctionsMeta = pikkuState(null, 'function', 'meta')
+  functions.push(...Object.keys(mainFunctionsMeta))
+
+  const externalPackages = pikkuState(null, 'rpc', 'externalPackages')
+  for (const [namespace, config] of externalPackages) {
+    const packageFunctionsMeta = pikkuState(config.package, 'function', 'meta')
+    for (const funcName of Object.keys(packageFunctionsMeta)) {
+      functions.push(`${namespace}:${funcName}`)
+    }
+  }
+
+  return functions
 }
 
 export const runPikkuFuncDirectly = async <In, Out>(
@@ -35,16 +113,18 @@ export const runPikkuFuncDirectly = async <In, Out>(
   allServices: CoreServices,
   wire: PikkuWire,
   data: In,
-  userSession?: SessionService<CoreUserSession>
+  userSession?: SessionService<CoreUserSession>,
+  packageName: string | null = null
 ) => {
-  const funcConfig = pikkuState('function', 'functions').get(funcName)
+  const funcConfig = pikkuState(packageName, 'function', 'functions').get(
+    funcName
+  )
   if (!funcConfig) {
     throw new Error(`Function not found: ${funcName}`)
   }
-  // Inject session into wire
   const wireWithSession = {
     ...wire,
-    session: userSession,
+    ...(userSession && createFunctionSessionWireProps(userSession)),
   }
   return (await funcConfig.func(allServices, data, wireWithSession)) as Out
 }
@@ -60,11 +140,15 @@ export const runPikkuFunc = async <In = any, Out = any>(
     auth: wiringAuth,
     inheritedMiddleware,
     wireMiddleware,
+    inheritedChannelMiddleware,
+    wireChannelMiddleware,
     inheritedPermissions,
     wirePermissions,
     coerceDataFromSchema,
     tags = [],
     wire,
+    sessionService,
+    packageName = null,
   }: {
     singletonServices: CoreSingletonServices
     createWireServices?: CreateWireServices
@@ -72,22 +156,77 @@ export const runPikkuFunc = async <In = any, Out = any>(
     auth?: boolean
     inheritedMiddleware?: MiddlewareMetadata[]
     wireMiddleware?: CorePikkuMiddleware[]
+    inheritedChannelMiddleware?: MiddlewareMetadata[]
+    wireChannelMiddleware?: CorePikkuChannelMiddleware[]
     inheritedPermissions?: PermissionMetadata[]
     wirePermissions?: CorePermissionGroup | CorePikkuPermission[]
     coerceDataFromSchema?: boolean
     tags?: string[]
     wire: PikkuWire
+    sessionService?: SessionService<CoreUserSession>
+    packageName?: string | null
   }
 ): Promise<Out> => {
-  const funcConfig = pikkuState('function', 'functions').get(funcName)
+  wire = {
+    ...wire,
+    wireType: wire.wireType ?? wireType,
+    wireId: wire.wireId ?? wireId,
+  }
+
+  const funcMap = pikkuState(packageName, 'function', 'functions')
+  let funcConfig = funcMap.get(funcName)
+  const allMeta = pikkuState(packageName, 'function', 'meta')
+  let funcMeta = allMeta[funcName]
+
+  if (!funcConfig || !funcMeta) {
+    const { baseName, version } = parseVersionedId(funcName)
+    if (version !== null) {
+      funcConfig = funcConfig || funcMap.get(baseName)
+      funcMeta = funcMeta || allMeta[baseName]
+      if (funcConfig && funcMeta) {
+        singletonServices.logger.warn(
+          `Version '${funcName}' not registered, resolved to '${baseName}'`
+        )
+      }
+    }
+  }
+
   if (!funcConfig) {
     throw new Error(`Function not found: ${funcName}`)
   }
-  const funcMeta = pikkuState('function', 'meta')[funcName]
   if (!funcMeta) {
     throw new Error(`Function meta not found: ${funcName}`)
   }
 
+  // For external packages, get or create their singleton services
+  const resolvedSingletonServices = packageName
+    ? await getOrCreatePackageSingletonServices(packageName, singletonServices)
+    : singletonServices
+
+  // Get the package's createWireServices if available
+  let resolvedCreateWireServices = createWireServices
+  if (packageName) {
+    const factories = pikkuState(packageName, 'package', 'factories')
+    if (factories?.createWireServices) {
+      resolvedCreateWireServices = factories.createWireServices
+    }
+  }
+
+  const allChannelMiddleware = combineChannelMiddleware(wireType, wireId, {
+    wireInheritedChannelMiddleware: inheritedChannelMiddleware,
+    wireChannelMiddleware,
+    packageName,
+  })
+
+  const resolvedWire =
+    allChannelMiddleware.length > 0 && wire.channel
+      ? wrapChannelWithMiddleware(
+          wire,
+          resolvedSingletonServices,
+          allChannelMiddleware
+        )
+      : wire
+
   // Convert tags to PermissionMetadata and merge with inheritedPermissions
   const mergedInheritedPermissions: PermissionMetadata[] = [
     ...(inheritedPermissions || []),
@@ -96,24 +235,38 @@ export const runPikkuFunc = async <In = any, Out = any>(
 
   // Helper function to run permissions and execute the function
   const executeFunction = async () => {
-    const initialSession = wire.session?.freezeInitial()
+    const functionWireProps = sessionService
+      ? createFunctionSessionWireProps(sessionService)
+      : undefined
 
-    const wireWithInitialSession: PikkuWire = {
-      ...wire,
-      initialSession,
+    const wireWithSession: PikkuWire = {
+      ...resolvedWire,
+      ...functionWireProps,
     }
 
-    if (wiringAuth === true || funcConfig.auth === true) {
-      // This means it was explicitly enabled in either wiring or function and has to be respected
-      if (!initialSession) {
+    const session = wireWithSession.session
+
+    if (funcMeta.sessionless) {
+      if (wiringAuth === true || funcConfig.auth === true) {
+        if (!session) {
+          throw new ForbiddenError('Authentication required')
+        }
+      }
+    } else if (funcMeta.sessionless === false) {
+      if (wiringAuth === false || funcConfig.auth === false) {
+        resolvedSingletonServices.logger.warn(
+          `Function '${funcName}' requires a session but auth was explicitly disabled — use pikkuSessionlessFunc instead.`
+        )
+      } else if (!session) {
         throw new ForbiddenError('Authentication required')
       }
-    }
-    if (wiringAuth === undefined && funcConfig.auth === undefined) {
-      // We always default to requiring auth unless explicitly disabled
-      if (!initialSession) {
-        // TODO: Critical, we need to figure out how to make this work with different wirings
-        // throw new ForbiddenError('Authentication required')
+    } else {
+      // TODO: Remove after a couple of releases — backward compat for
+      // generated metadata that doesn't include the `sessionless` field yet.
+      if (wiringAuth === true || funcConfig.auth === true) {
+        if (!session) {
+          throw new ForbiddenError('Authentication required')
+        }
       }
     }
 
@@ -125,14 +278,15 @@ export const runPikkuFunc = async <In = any, Out = any>(
     if (inputSchemaName) {
       // Validate request data against the defined schema, if any
       await validateSchema(
-        singletonServices.logger,
-        singletonServices.schema,
+        resolvedSingletonServices.logger,
+        resolvedSingletonServices.schema,
         inputSchemaName,
-        actualData
+        actualData,
+        packageName
       )
       // Coerce (top level) query string parameters or date objects if specified by the schema
       if (coerceDataFromSchema) {
-        coerceTopLevelDataFromSchema(inputSchemaName, actualData)
+        coerceTopLevelDataFromSchema(inputSchemaName, actualData, packageName)
       }
     }
 
@@ -141,28 +295,28 @@ export const runPikkuFunc = async <In = any, Out = any>(
       wirePermissions: wirePermissions,
       funcInheritedPermissions: funcMeta.permissions,
       funcPermissions: funcConfig.permissions,
-      services: singletonServices,
-      wire: { ...wireWithInitialSession, rpc: undefined } as any,
+      services: resolvedSingletonServices,
+      wire: { ...wireWithSession, rpc: undefined } as any,
       data: actualData,
+      packageName,
     })
 
-    const wireServices = await createWireServices?.(
-      singletonServices,
-      wireWithInitialSession
+    const wireServices = await resolvedCreateWireServices?.(
+      resolvedSingletonServices,
+      wireWithSession
     )
     try {
-      const services = { ...singletonServices, ...wireServices }
-      const rpc = rpcService.getContextRPCService(
-        services,
-        wireWithInitialSession
-      )
+      const services = { ...resolvedSingletonServices, ...wireServices }
+      const rpc = rpcService.getContextRPCService(services, wireWithSession, {
+        sessionService,
+      })
       return await funcConfig.func(services, actualData, {
-        ...wireWithInitialSession,
+        ...wireWithSession,
         rpc,
       })
     } finally {
       if (wireServices) {
-        await closeWireServices(singletonServices.logger, wireServices)
+        await closeWireServices(resolvedSingletonServices.logger, wireServices)
       }
     }
   }
@@ -172,12 +326,13 @@ export const runPikkuFunc = async <In = any, Out = any>(
     wireMiddleware,
     funcInheritedMiddleware: funcMeta.middleware,
     funcMiddleware: funcConfig.middleware,
+    packageName,
   })
 
   if (allMiddleware.length > 0) {
     return (await runMiddleware<CorePikkuMiddleware>(
-      singletonServices,
-      wire,
+      resolvedSingletonServices,
+      resolvedWire,
       allMiddleware,
       executeFunction
     )) as Out

package/src/function/functions.types.ts

@@ -6,7 +6,14 @@ import type {
   PikkuWire,
   PickRequired,
 } from '../types/core.types.js'
-import { Session } from 'inspector'
+import type { StandardSchemaV1 } from '@standard-schema/spec'
+import type { CoreNodeConfig } from '../wirings/node/node.types.js'
+
+/**
+ * @deprecated Use StandardSchemaV1 from @standard-schema/spec instead.
+ * This alias exists only for backward compatibility with generated code.
+ */
+export type ZodLike<T = any> = StandardSchemaV1<T, T>
 
 /**
  * Represents a core API function that performs an operation using core services and a user session.
@@ -20,6 +27,7 @@ export type CorePikkuFunction<
   In,
   Out,
   Services extends CoreSingletonServices = CoreServices,
+  Session extends CoreUserSession = CoreUserSession,
   Wire extends PikkuWire<In, Out> = PikkuWire<In, Out, true, Session>,
 > = (
   services: Services,
@@ -39,15 +47,16 @@ export type CorePikkuFunctionSessionless<
   In,
   Out,
   Services extends CoreSingletonServices = CoreServices,
-  Wire extends PikkuWire<
+  Session extends CoreUserSession = CoreUserSession,
+  Wire extends PikkuWire<In, Out, false, Session, any, any, any> = PikkuWire<
     In,
     Out,
     false,
-    CoreUserSession,
+    Session,
     any,
     any,
     any
-  > = PikkuWire<In, Out, false, CoreUserSession, any, any, any>,
+  >,
 > = (
   services: Services,
   data: In,
@@ -108,8 +117,8 @@ export type CorePikkuPermissionConfig<
  * ```typescript
  * // Direct function syntax
  * export const adminPermission = pikkuPermission(
- *   async ({ logger }, _data, { session }) => {
- *     const currentSession = await session.get()
+ *   async ({ logger }, _data, { getSession }) => {
+ *     const currentSession = await getSession()
  *     return currentSession?.role === 'admin'
  *   }
  * )
@@ -118,8 +127,8 @@ export type CorePikkuPermissionConfig<
  * export const adminPermission = pikkuPermission({
  *   name: 'Admin Permission',
  *   description: 'Checks if user has admin role',
- *   func: async ({ logger }, _data, { session }) => {
- *     const currentSession = await session.get()
+ *   func: async ({ logger }, _data, { getSession }) => {
+ *     const currentSession = await getSession()
  *     return currentSession?.role === 'admin'
  *   }
  * })
@@ -168,8 +177,8 @@ export type CorePikkuPermissionFactory<
  * export const requireRole = pikkuPermissionFactory<{ role: string }>(({
  *   role
  * }) => {
- *   return pikkuPermission(async ({ logger }, data, { session }) => {
- *      const currentSession = await session.get()
+ *   return pikkuPermission(async ({ logger }, data, { getSession }) => {
+ *      const currentSession = await getSession()
  *     if (!currentSession || currentSession.role !== role) {
  *       logger.warn(`Permission denied: required role '${role}'`)
  *       return false
@@ -185,14 +194,45 @@ export const pikkuPermissionFactory = <In = any>(
   return factory
 }
 
+export type CorePikkuAuth<
+  Services extends CoreSingletonServices = CoreServices,
+  Session extends CoreUserSession = CoreUserSession,
+> = (services: Services, session: Session) => Promise<boolean> | boolean
+
+export type CorePikkuAuthConfig<
+  Services extends CoreSingletonServices = CoreServices,
+  Session extends CoreUserSession = CoreUserSession,
+> = {
+  func: CorePikkuAuth<Services, Session>
+  name?: string
+  description?: string
+}
+
+export const pikkuAuth = <
+  Services extends CoreSingletonServices = CoreServices,
+  Session extends CoreUserSession = CoreUserSession,
+>(
+  auth:
+    | CorePikkuAuth<Services, Session>
+    | CorePikkuAuthConfig<Services, Session>
+): CorePikkuPermission<any, Services, any> => {
+  const fn = typeof auth === 'function' ? auth : auth.func
+  const wrapper = async (services: Services, _data: any, wire: any) => {
+    const session = wire.session
+    if (!session) return false
+    return fn(services, session as Session)
+  }
+  return wrapper as any
+}
+
 export type CorePermissionGroup<PikkuPermission = CorePikkuPermission<any>> =
   | Record<string, PikkuPermission | PikkuPermission[]>
   | undefined
 
 export type CorePikkuFunctionConfig<
   PikkuFunction extends
-    | CorePikkuFunction<any, any, any, any>
-    | CorePikkuFunctionSessionless<any, any, any, any>,
+    | CorePikkuFunction<any, any, any, any, any>
+    | CorePikkuFunctionSessionless<any, any, any, any, any>,
   PikkuPermission extends CorePikkuPermission<
     any,
     any,
@@ -202,13 +242,25 @@ export type CorePikkuFunctionConfig<
     any,
     any
   >,
+  InputSchema extends StandardSchemaV1 | undefined = undefined,
+  OutputSchema extends StandardSchemaV1 | undefined = undefined,
 > = {
-  name?: string
+  /** Optional human-readable title for the function */
+  title?: string
+  /** Optional description of what the function does */
+  description?: string
+  override?: string
+  version?: number
   tags?: string[]
   expose?: boolean
-  internal?: boolean
+  remote?: boolean
+  mcp?: boolean
+  requiresApproval?: boolean
   func: PikkuFunction
   auth?: boolean
   permissions?: CorePermissionGroup<PikkuPermission>
   middleware?: PikkuMiddleware[]
+  input?: InputSchema
+  output?: OutputSchema
+  node?: CoreNodeConfig
 }

package/src/function/index.ts

@@ -1,2 +1,5 @@
-export * from './function-runner.js'
-export * from './functions.types.js'
+export { addFunction, getAllFunctionNames } from './function-runner.js'
+export type {
+  CorePikkuFunction,
+  CorePikkuFunctionSessionless,
+} from './functions.types.js'

package/src/handle-error.ts

@@ -57,17 +57,9 @@ export const handleHTTPError = (
     }
   }
 
-  // Handle 404 errors specifically
-  if (e instanceof NotFoundError) {
-    // TODO
-    // http?.response?.end()
-  }
-
-  // Either bubble up or end the response
   if (bubbleError) {
     throw e
-  } else {
-    // TODO
-    // http?.response?.end()
   }
+
+  http?.response?.close?.()
 }