@pikku/core 0.12.4 → 0.12.5

package/src/function/function-runner.ts

@@ -0,0 +1,365 @@
+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'
+import type {
+  CoreServices,
+  CoreUserSession,
+  CorePikkuMiddleware,
+  PikkuWiringTypes,
+  PikkuWire,
+  MiddlewareMetadata,
+  PermissionMetadata,
+  CoreSingletonServices,
+  CreateWireServices,
+  CoreConfig,
+} from '../types/core.types.js'
+import type { CorePikkuChannelMiddleware } from '../wirings/channel/channel.types.js'
+import type {
+  CorePermissionGroup,
+  CorePikkuFunctionConfig,
+  CorePikkuPermission,
+} from './functions.types.js'
+import { parseVersionedId } from '../version.js'
+import type { SessionService } from '../services/user-session-service.js'
+import { createFunctionSessionWireProps } from '../services/user-session-service.js'
+import { ForbiddenError, ReadonlySessionError } from '../errors/errors.js'
+import { rpcService } from '../wirings/rpc/rpc-runner.js'
+import { closeWireServices } from '../utils.js'
+
+/**
+ * Get or create singleton services for an addon package.
+ * Services are cached in pikkuState to avoid recreation on each call.
+ *
+ * @param packageName - The addon 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>,
+  packageName: string | null = null
+) => {
+  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 addons = pikkuState(null, 'addons', 'packages')
+  for (const [namespace, config] of addons) {
+    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>(
+  funcName: string,
+  allServices: CoreServices,
+  wire: PikkuWire,
+  data: In,
+  userSession?: SessionService<CoreUserSession>,
+  packageName: string | null = null
+) => {
+  const funcConfig = pikkuState(packageName, 'function', 'functions').get(
+    funcName
+  )
+  if (!funcConfig) {
+    throw new Error(`Function not found: ${funcName}`)
+  }
+  const wireWithSession = {
+    ...wire,
+    ...(userSession && createFunctionSessionWireProps(userSession)),
+  }
+  return (await funcConfig.func(allServices, data, wireWithSession)) as Out
+}
+
+export const runPikkuFunc = async <In = any, Out = any>(
+  wireType: PikkuWiringTypes,
+  wireId: string,
+  funcName: string,
+  {
+    singletonServices,
+    createWireServices,
+    data,
+    auth: wiringAuth,
+    inheritedMiddleware,
+    wireMiddleware,
+    inheritedChannelMiddleware,
+    wireChannelMiddleware,
+    inheritedPermissions,
+    wirePermissions,
+    coerceDataFromSchema,
+    tags = [],
+    wire,
+    sessionService,
+    packageName = null,
+  }: {
+    singletonServices: CoreSingletonServices
+    createWireServices?: CreateWireServices
+    data: () => Promise<In> | In
+    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> => {
+  wire.wireType ??= wireType
+  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}`)
+  }
+  if (!funcMeta) {
+    throw new Error(`Function meta not found: ${funcName}`)
+  }
+
+  // For addon 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
+  let mergedInheritedPermissions: PermissionMetadata[]
+  if (tags && tags.length > 0) {
+    mergedInheritedPermissions = [
+      ...(inheritedPermissions || []),
+      ...tags.map((tag) => ({ type: 'tag' as const, tag })),
+    ]
+  } else {
+    mergedInheritedPermissions = inheritedPermissions || []
+  }
+
+  // Helper function to run permissions and execute the function
+  const executeFunction = async () => {
+    if (sessionService) {
+      resolvedWire.session = sessionService.freezeInitial()
+      resolvedWire.setSession = (s: any) => sessionService.set(s)
+      resolvedWire.clearSession = () => sessionService.clear()
+      resolvedWire.getSession = () => sessionService.get()
+      resolvedWire.hasSessionChanged = () => sessionService.sessionChanged
+    }
+
+    const session = resolvedWire.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.`
+        )
+      }
+      if (!session) {
+        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')
+        }
+      }
+    }
+
+    if ((session as any)?.readonly && !funcMeta.readonly) {
+      throw new ReadonlySessionError()
+    }
+
+    // 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) {
+      // Coerce (top level) data types before validation (e.g. string→array, string→date)
+      if (coerceDataFromSchema) {
+        coerceTopLevelDataFromSchema(inputSchemaName, actualData, packageName)
+      }
+      // Validate request data against the defined schema, if any
+      await validateSchema(
+        resolvedSingletonServices.logger,
+        resolvedSingletonServices.schema,
+        inputSchemaName,
+        actualData,
+        packageName
+      )
+    }
+
+    if (
+      mergedInheritedPermissions.length > 0 ||
+      wirePermissions ||
+      funcMeta.permissions ||
+      funcConfig.permissions
+    ) {
+      await runPermissions(wireType, wireId, {
+        wireInheritedPermissions: mergedInheritedPermissions,
+        wirePermissions: wirePermissions,
+        funcInheritedPermissions: funcMeta.permissions,
+        funcPermissions: funcConfig.permissions,
+        services: resolvedSingletonServices,
+        wire: resolvedWire as any,
+        data: actualData,
+        packageName,
+      })
+    }
+
+    const wireServices = await resolvedCreateWireServices?.(
+      resolvedSingletonServices,
+      resolvedWire
+    )
+    try {
+      const services =
+        wireServices && Object.keys(wireServices).length > 0
+          ? { ...resolvedSingletonServices, ...wireServices }
+          : resolvedSingletonServices
+      Object.defineProperty(resolvedWire, 'rpc', {
+        get() {
+          const rpc = rpcService.getContextRPCService(services, resolvedWire, {
+            sessionService,
+          })
+          Object.defineProperty(resolvedWire, 'rpc', {
+            value: rpc,
+            writable: true,
+            configurable: true,
+          })
+          return rpc
+        },
+        configurable: true,
+        enumerable: true,
+      })
+      return await funcConfig.func(services, actualData, resolvedWire)
+    } finally {
+      if (wireServices && Object.keys(wireServices).length > 0) {
+        await closeWireServices(resolvedSingletonServices.logger, wireServices)
+      }
+    }
+  }
+
+  const allMiddleware = combineMiddleware(wireType, wireId, {
+    wireInheritedMiddleware: inheritedMiddleware,
+    wireMiddleware,
+    funcInheritedMiddleware: funcMeta.middleware,
+    funcMiddleware: funcConfig.middleware,
+    packageName,
+  })
+
+  if (allMiddleware.length > 0) {
+    return (await runMiddleware<CorePikkuMiddleware>(
+      resolvedSingletonServices,
+      resolvedWire,
+      allMiddleware,
+      executeFunction
+    )) as Out
+  }
+
+  return (await executeFunction()) as Out
+}

package/src/function/functions.types.ts

@@ -0,0 +1,304 @@
+import type {
+  CoreServices,
+  CoreSingletonServices,
+  CoreUserSession,
+  CorePikkuMiddleware,
+  PikkuWire,
+  PickRequired,
+} from '../types/core.types.js'
+import type { StandardSchemaV1 } from '@standard-schema/spec'
+import type { PikkuError } from '../errors/error-handler.js'
+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.
+ *
+ * @template In - The input type.
+ * @template Out - The output type.
+ * @template Services - The services type, defaults to `CoreServices`.
+ * @template Wire - The wire type, defaults to `PikkuWire<In, Out>`.
+ */
+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,
+  data: In,
+  wire: Wire
+) => Wire['channel'] extends null ? Promise<Out> : Promise<Out> | Promise<void>
+
+/**
+ * Represents a core API function that can be used without a session.
+ *
+ * @template In - The input type.
+ * @template Out - The output type.
+ * @template Services - The services type, defaults to `CoreServices`.
+ * @template Wire - The wire type, defaults to `PikkuWire<In, Out>`.
+ */
+export type CorePikkuFunctionSessionless<
+  In,
+  Out,
+  Services extends CoreSingletonServices = CoreServices,
+  Session extends CoreUserSession = CoreUserSession,
+  Wire extends PikkuWire<In, Out, false, Session, any, any, any> = PikkuWire<
+    In,
+    Out,
+    false,
+    Session,
+    any,
+    any,
+    any
+  >,
+> = (
+  services: Services,
+  data: In,
+  wire: Wire
+) => Wire['channel'] extends null ? Promise<Out> : Promise<Out> | Promise<void>
+
+/**
+ * Represents a function that checks permissions for a given operation.
+ *
+ * @template In - The input type.
+ * @template Services - The services type, defaults to `CoreServices`.
+ * @template Session - The session type, defaults to `CoreUserSession`.
+ */
+export type CorePikkuPermission<
+  In = any,
+  Services extends CoreSingletonServices = CoreServices,
+  Wire extends PikkuWire<
+    In,
+    never,
+    false,
+    CoreUserSession,
+    any,
+    never,
+    never
+  > = PikkuWire<In, never, false, CoreUserSession, never, never, never>,
+> = (services: Services, data: In, wire: Wire) => 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,
+  Wire extends PikkuWire<In, never, false, CoreUserSession> = PikkuWire<
+    In,
+    never,
+    false,
+    CoreUserSession
+  >,
+> = {
+  /** The permission function */
+  func: CorePikkuPermission<In, Services, Wire>
+  /** 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, { getSession }) => {
+ *     const currentSession = await getSession()
+ *     return currentSession?.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, { getSession }) => {
+ *     const currentSession = await getSession()
+ *     return currentSession?.role === 'admin'
+ *   }
+ * })
+ * ```
+ */
+export const pikkuPermission = <
+  In = any,
+  Services extends CoreSingletonServices = CoreServices,
+  Wire extends PickRequired<
+    PikkuWire<In, never, false, CoreUserSession>,
+    'session'
+  > = PickRequired<PikkuWire<In, never, false, CoreUserSession>, 'session'>,
+>(
+  permission:
+    | CorePikkuPermission<In, Services, Wire>
+    | CorePikkuPermissionConfig<In, Services, Wire>
+): CorePikkuPermission<In, Services, Wire> => {
+  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,
+  Wire extends PikkuWire<In, never, false, CoreUserSession> = PikkuWire<
+    In,
+    never,
+    false,
+    CoreUserSession
+  >,
+> = (input: In) => CorePikkuPermission<any, Services, Wire>
+
+/**
+ * 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, { getSession }) => {
+ *      const currentSession = await getSession()
+ *     if (!currentSession || currentSession.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
+}
+
+/**
+ * A function that generates a human-readable description of a pending approval action.
+ * Used by AI agents to show meaningful approval prompts instead of raw tool arguments.
+ *
+ * @template In - The input type (same as the function it describes).
+ * @template Services - The services type, defaults to `CoreSingletonServices`.
+ */
+export type CorePikkuApprovalDescription<
+  In = any,
+  Services extends CoreSingletonServices = CoreSingletonServices,
+> = (services: Services, data: In) => Promise<string>
+
+/**
+ * Factory function for creating approval description functions with tree-shaking support.
+ *
+ * @example
+ * ```typescript
+ * export const deleteTodoApproval = pikkuApprovalDescription(
+ *   async ({ todoStore }, { id }) => {
+ *     const todo = await todoStore.get(id)
+ *     return `Delete todo: "${todo.title}"`
+ *   }
+ * )
+ * ```
+ */
+export const pikkuApprovalDescription = <
+  In = any,
+  Services extends CoreSingletonServices = CoreSingletonServices,
+>(
+  fn: CorePikkuApprovalDescription<In, Services>
+): CorePikkuApprovalDescription<In, Services> => {
+  return fn
+}
+
+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, any>
+    | CorePikkuFunctionSessionless<any, any, any, any, any>,
+  PikkuPermission extends CorePikkuPermission<
+    any,
+    any,
+    any
+  > = CorePikkuPermission<any>,
+  PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<
+    any,
+    any
+  >,
+  InputSchema extends StandardSchemaV1 | undefined = undefined,
+  OutputSchema extends StandardSchemaV1 | undefined = undefined,
+> = {
+  /** 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
+  remote?: boolean
+  mcp?: boolean
+  readonly?: boolean
+  approvalRequired?: boolean
+  approvalDescription?: any
+  func: PikkuFunction
+  auth?: boolean
+  permissions?: CorePermissionGroup<PikkuPermission>
+  middleware?: PikkuMiddleware[]
+  input?: InputSchema
+  output?: OutputSchema
+  node?: CoreNodeConfig
+  errors?: Array<typeof PikkuError>
+}

package/src/function/index.ts

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