@pikku/core 0.11.0 → 0.11.2

package/src/types/core.types.ts

@@ -1,9 +1,10 @@
 import type { Logger, LogLevel } from '../services/logger.js'
 import { VariablesService } from '../services/variables-service.js'
+import { SecretService } from '../services/secret-service.js'
 import { SchemaService } from '../services/schema-service.js'
 import { JWTService } from '../services/jwt-service.js'
 import { PikkuHTTP } from '../wirings/http/http.types.js'
-import { UserSessionService } from '../services/user-session-service.js'
+import { SessionService } from '../services/user-session-service.js'
 import { PikkuChannel } from '../wirings/channel/channel.types.js'
 import { PikkuRPC } from '../wirings/rpc/rpc-types.js'
 import { PikkuMCP } from '../wirings/mcp/mcp.types.js'
@@ -11,23 +12,24 @@ import { PikkuScheduledTask } from '../wirings/scheduler/scheduler.types.js'
 import { PikkuQueue, QueueService } from '../wirings/queue/queue.types.js'
 import { PikkuCLI } from '../wirings/cli/cli.types.js'
 import {
-  PikkuWorkflowInteraction,
+  PikkuWorkflowWire,
   WorkflowService,
   WorkflowServiceConfig,
-  WorkflowStepInteraction,
+  WorkflowStepWire,
 } from '../wirings/workflow/workflow.types.js'
+import type { PikkuGraphWire } from '../wirings/workflow/graph/workflow-graph.types.js'
+import { PikkuTrigger } from '../wirings/trigger/trigger.types.js'
 import { SchedulerService } from '../services/scheduler-service.js'
 
-export enum PikkuWiringTypes {
-  http = 'http',
-  scheduler = 'scheduler',
-  channel = 'channel',
-  rpc = 'rpc',
-  queue = 'queue',
-  mcp = 'mcp',
-  cli = 'cli',
-  workflow = 'workflow',
-}
+export type PikkuWiringTypes =
+  | 'http'
+  | 'scheduler'
+  | 'channel'
+  | 'rpc'
+  | 'queue'
+  | 'mcp'
+  | 'cli'
+  | 'workflow'
 
 export interface FunctionServicesMeta {
   optimized: boolean
@@ -85,17 +87,18 @@ export type FunctionRuntimeMeta = {
 }
 
 export type FunctionMeta = FunctionRuntimeMeta &
-  Partial<{
-    name: string
-    services: FunctionServicesMeta
-    inputs: string[] | null
-    outputs: string[] | null
-    tags: string[]
-    docs: PikkuDocs
-    isDirectFunction: boolean // true if it's pikkuFunc(fn), false if it's pikkuFunc({ func: fn })
-    middleware: MiddlewareMetadata[] // Function-level middleware
-    permissions: PermissionMetadata[] // Function-level permissions
-  }>
+  Partial<
+    {
+      name: string
+      services: FunctionServicesMeta
+      usedWires: string[]
+      inputs: string[] | null
+      outputs: string[] | null
+      middleware: MiddlewareMetadata[]
+      permissions: PermissionMetadata[]
+      isDirectFunction: boolean
+    } & CommonWireMeta
+  >
 
 export type FunctionsRuntimeMeta = Record<string, FunctionRuntimeMeta>
 export type FunctionsMeta = Record<string, FunctionMeta>
@@ -169,6 +172,8 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
   logger: Logger
   /** The variable service to be used */
   variables: VariablesService
+  /** The secrets service to retrieve secrets */
+  secrets: SecretService
   /** The workflow orchestrator service */
   workflowService?: WorkflowService
   /** The queue service */
@@ -178,31 +183,47 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
 }
 
 /**
- * Represents different forms of interaction within Pikku and the outside world.
+ * Represents different forms of wire within Pikku and the outside world.
  */
-export type PikkuInteraction<In = unknown, Out = unknown> = Partial<{
+export type PikkuWire<
+  In = unknown,
+  Out = unknown,
+  HasInitialSession extends boolean = false,
+  UserSession extends CoreUserSession = CoreUserSession,
+  TypedRPC extends PikkuRPC = PikkuRPC,
+  IsChannel extends true | null = null,
+  MCPTools extends string | never = never,
+  TypedWorkflow extends PikkuWorkflowWire | never = PikkuWorkflowWire,
+  TriggerOutput = unknown,
+> = Partial<{
   http: PikkuHTTP<In>
-  mcp: PikkuMCP
-  rpc: PikkuRPC
-  channel: PikkuChannel<unknown, Out>
+  mcp: PikkuMCP<MCPTools>
+  rpc: TypedRPC
+  channel: [IsChannel] extends [null]
+    ? PikkuChannel<unknown, Out>
+    : PikkuChannel<unknown, Out> | undefined
   scheduledTask: PikkuScheduledTask
   queue: PikkuQueue
   cli: PikkuCLI
-  workflow: PikkuWorkflowInteraction
-  workflowStep: WorkflowStepInteraction
+  workflow: TypedWorkflow
+  workflowStep: WorkflowStepWire
+  graph: PikkuGraphWire
+  trigger: PikkuTrigger<TriggerOutput>
+  initialSession: HasInitialSession extends true
+    ? UserSession
+    : UserSession | undefined
+  session: SessionService<UserSession>
 }>
 
 /**
- * A function that can wrap an interaction and be called before or after
+ * A function that can wrap an wire and be called before or after
  */
 export type CorePikkuMiddleware<
   SingletonServices extends CoreSingletonServices = CoreSingletonServices,
   UserSession extends CoreUserSession = CoreUserSession,
 > = (
-  services: SingletonServices & {
-    userSession: UserSessionService<UserSession>
-  },
-  interactions: PikkuInteraction,
+  services: SingletonServices,
+  wires: PikkuWire<unknown, unknown, false, UserSession>,
   next: () => Promise<void>
 ) => Promise<void>
 
@@ -218,8 +239,8 @@ export type CorePikkuMiddlewareConfig<
 > = {
   /** The middleware function */
   func: CorePikkuMiddleware<SingletonServices, UserSession>
-  /** Optional human-readable name for the middleware */
-  name?: string
+  /** Optional human-readable title for the middleware */
+  title?: string
   /** Optional description of what the middleware does */
   description?: string
 }
@@ -254,7 +275,7 @@ export type CorePikkuMiddlewareGroup<
  * ```typescript
  * // Direct function syntax
  * export const logMiddleware = pikkuMiddleware(
- *   async ({ logger }, _interaction, next) => {
+ *   async ({ logger }, next) => {
  *     logger.info('Request started')
  *     await next()
  *   }
@@ -262,9 +283,9 @@ export type CorePikkuMiddlewareGroup<
  *
  * // Configuration object syntax with metadata
  * export const logMiddleware = pikkuMiddleware({
- *   name: 'Request Logger',
+ *   title: 'Request Logger',
  *   description: 'Logs request information',
- *   func: async ({ logger }, _interaction, next) => {
+ *   func: async ({ logger }, next) => {
  *     logger.info('Request started')
  *     await next()
  *   }
@@ -292,7 +313,7 @@ export const pikkuMiddleware = <
  *   message,
  *   level = 'info'
  * }) => {
- *   return pikkuMiddleware(async ({ logger }, _interaction, next) => {
+ *   return pikkuMiddleware(async ({ logger }, next) => {
  *     logger[level](message)
  *     await next()
  *   })
@@ -306,20 +327,15 @@ export const pikkuMiddlewareFactory = <In = any>(
 }
 
 /**
- * Represents the core services used by Pikku, including singleton services and the request/response interaction.
+ * Represents the core services used by Pikku, including singleton services.
  */
-export type CoreServices<
-  SingletonServices = CoreSingletonServices,
-  UserSession extends CoreUserSession = CoreUserSession,
-> = SingletonServices &
-  PikkuInteraction & {
-    userSession?: UserSessionService<UserSession>
-  }
+export type CoreServices<SingletonServices = CoreSingletonServices> =
+  SingletonServices
 
-export type SessionServices<
+export type WireServices<
   SingletonServices extends CoreSingletonServices = CoreSingletonServices,
   Services = CoreServices<SingletonServices>,
-> = Omit<Services, keyof SingletonServices | keyof PikkuInteraction | 'session'>
+> = Omit<Services, keyof SingletonServices | 'session'>
 
 /**
  * Defines a function type for creating singleton services from the given configuration.
@@ -335,16 +351,15 @@ export type CreateSingletonServices<
 /**
  * Defines a function type for creating session-specific services.
  */
-export type CreateSessionServices<
+export type CreateWireServices<
   SingletonServices extends CoreSingletonServices = CoreSingletonServices,
   Services extends
     CoreServices<SingletonServices> = CoreServices<SingletonServices>,
   UserSession extends CoreUserSession = CoreUserSession,
 > = (
   services: SingletonServices,
-  interaction: PikkuInteraction,
-  session: UserSession | undefined
-) => Promise<SessionServices<Services, SingletonServices>>
+  wire: PikkuWire<unknown, unknown, false, UserSession>
+) => Promise<WireServices<Services, SingletonServices>>
 
 /**
  * Defines a function type for creating config.
@@ -357,11 +372,17 @@ export type CreateConfig<
 /**
  * Represents the documentation for a route, including summary, description, tags, and errors.
  */
-export type PikkuDocs = {
+export type CommonWireMeta = {
+  pikkuFuncName: string
+
+  title?: string
+  tags?: string[]
   summary?: string
   description?: string
-  tags?: string[]
   errors?: string[]
+
+  middleware?: MiddlewareMetadata[]
+  permissions?: PermissionMetadata[]
 }
 
 /**

package/src/types/state.types.ts

@@ -0,0 +1,195 @@
+import { PikkuError, ErrorDetails } from '../errors/error-handler.js'
+import {
+  CorePikkuFunctionConfig,
+  CorePermissionGroup,
+  CorePikkuPermission,
+} from '../function/functions.types.js'
+import { CoreChannel, ChannelsMeta } from '../wirings/channel/channel.types.js'
+import { CLIMeta, CLIProgramState } from '../wirings/cli/cli.types.js'
+import {
+  HTTPMethod,
+  CoreHTTPFunctionWiring,
+  HTTPWiringsMeta,
+} from '../wirings/http/http.types.js'
+import {
+  CoreMCPResource,
+  MCPResourceMeta,
+  CoreMCPTool,
+  MCPToolMeta,
+  CoreMCPPrompt,
+  MCPPromptMeta,
+} from '../wirings/mcp/mcp.types.js'
+import {
+  CoreQueueWorker,
+  QueueWorkersMeta,
+} from '../wirings/queue/queue.types.js'
+import {
+  CoreScheduledTask,
+  ScheduledTasksMeta,
+} from '../wirings/scheduler/scheduler.types.js'
+import {
+  CoreWorkflow,
+  WorkflowsRuntimeMeta,
+  WorkflowWires,
+} from '../wirings/workflow/workflow.types.js'
+import type {
+  WorkflowGraphDefinition,
+  GraphNodeConfig,
+} from '../wirings/workflow/graph/workflow-graph.types.js'
+import { CoreTrigger, TriggerMeta } from '../wirings/trigger/trigger.types.js'
+import {
+  FunctionsMeta,
+  CorePikkuMiddleware,
+  CorePikkuMiddlewareGroup,
+  FunctionServicesMeta,
+  CreateConfig,
+  CreateSingletonServices,
+  CreateWireServices,
+  CoreConfig,
+  CoreSingletonServices,
+  CoreServices,
+  CoreUserSession,
+} from './core.types.js'
+
+/**
+ * State structure for an individual package
+ */
+export interface PikkuPackageState {
+  function: {
+    meta: FunctionsMeta
+    functions: Map<string, CorePikkuFunctionConfig<any, any>>
+  }
+  rpc: {
+    meta: Record<string, string>
+    files: Map<
+      string,
+      {
+        exportedName: string
+        path: string
+      }
+    >
+    /** Maps namespace aliases to package names (e.g., 'ext' -> '@pikku/templates-function-external') */
+    externalPackages: Map<string, string>
+  }
+  http: {
+    middleware: Map<string, CorePikkuMiddleware<any, any>[]>
+    permissions: Map<string, CorePermissionGroup | CorePikkuPermission[]>
+    routes: Map<HTTPMethod, Map<string, CoreHTTPFunctionWiring<any, any, any>>>
+    meta: HTTPWiringsMeta
+  }
+  channel: {
+    channels: Map<string, CoreChannel<any, any>>
+    meta: ChannelsMeta
+  }
+  scheduler: {
+    tasks: Map<string, CoreScheduledTask>
+    meta: ScheduledTasksMeta
+  }
+  queue: {
+    registrations: Map<string, CoreQueueWorker>
+    meta: QueueWorkersMeta
+  }
+  workflows: {
+    registrations: Map<string, CoreWorkflow>
+    graphRegistrations: Map<string, WorkflowGraphDefinition<any>>
+    /** DSL workflow wirings (from wireWorkflow({ func: ... })) */
+    wirings: Map<any, { wires: WorkflowWires; func: any }>
+    /** Graph workflow wirings (from wireWorkflow({ graph: ... })) */
+    graphWirings: Map<
+      any,
+      { wires: WorkflowWires; graph: Record<string, GraphNodeConfig<string>> }
+    >
+    meta: WorkflowsRuntimeMeta
+  }
+  trigger: {
+    triggers: Map<string, CoreTrigger>
+    meta: TriggerMeta
+  }
+  mcp: {
+    resources: Map<string, CoreMCPResource>
+    resourcesMeta: MCPResourceMeta
+    tools: Map<string, CoreMCPTool>
+    toolsMeta: MCPToolMeta
+    prompts: Map<string, CoreMCPPrompt>
+    promptsMeta: MCPPromptMeta
+  }
+  cli: {
+    meta: CLIMeta | Record<string, any> // Backward compatible with old published CLI format
+    programs: Record<string, CLIProgramState>
+  }
+  middleware: {
+    tagGroup: Record<string, CorePikkuMiddlewareGroup>
+    httpGroup: Record<string, CorePikkuMiddlewareGroup>
+    tagGroupMeta: Record<
+      string,
+      {
+        exportName: string | null
+        sourceFile: string
+        position: number
+        services: FunctionServicesMeta
+        middlewareCount: number
+        isFactory: boolean
+      }
+    >
+    httpGroupMeta: Record<
+      string,
+      {
+        exportName: string | null
+        sourceFile: string
+        position: number
+        services: FunctionServicesMeta
+        middlewareCount: number
+        isFactory: boolean
+      }
+    >
+  }
+  permissions: {
+    tagGroup: Record<string, CorePermissionGroup | CorePikkuPermission[]>
+    httpGroup: Record<string, CorePermissionGroup | CorePikkuPermission[]>
+    tagGroupMeta: Record<
+      string,
+      {
+        exportName: string | null
+        sourceFile: string
+        position: number
+        services: FunctionServicesMeta
+        permissionCount: number
+        isFactory: boolean
+      }
+    >
+    httpGroupMeta: Record<
+      string,
+      {
+        exportName: string | null
+        sourceFile: string
+        position: number
+        services: FunctionServicesMeta
+        permissionCount: number
+        isFactory: boolean
+      }
+    >
+  }
+  misc: {
+    errors: Map<PikkuError, ErrorDetails>
+    schemas: Map<string, any>
+    middleware: Record<string, CorePikkuMiddleware[]>
+    permissions: Record<string, CorePermissionGroup | CorePikkuPermission[]>
+  }
+  package: {
+    /** Service factory functions for external packages */
+    factories: {
+      createConfig?: CreateConfig<CoreConfig>
+      createSingletonServices?: CreateSingletonServices<
+        CoreConfig,
+        CoreSingletonServices
+      >
+      createWireServices?: CreateWireServices<
+        CoreSingletonServices,
+        CoreServices,
+        CoreUserSession
+      >
+    } | null
+    /** Cached singleton services for this package */
+    singletonServices: CoreSingletonServices | null
+  }
+}

package/src/utils.ts

@@ -1,14 +1,15 @@
 import { Logger } from './services/logger.js'
+import { CoreSingletonServices } from './types/core.types.js'
 
-// TODO: SessionServices probably needs it's own type
+// TODO: WireServices probably needs it's own type
 // but is an issue for the future and will be tackled
 // with dependency injection
-export const closeSessionServices = async (
+export const closeWireServices = async (
   logger: Logger,
-  sessionServices: Record<string, any>
+  wireServices: Record<string, any>
 ) => {
   await Promise.all(
-    Object.values(sessionServices).map(async (service) => {
+    Object.values(wireServices).map(async (service) => {
       if (service?.close) {
         try {
           await service.close()
@@ -57,3 +58,57 @@ export const freezeDedupe = <T>(
   }
   return Object.freeze(out)
 }
+
+/**
+ * Stop a single service by calling its stop method if it exists
+ */
+const stopService = async (
+  logger: Logger,
+  name: string,
+  service: any
+): Promise<void> => {
+  const stop = service?.stop
+  if (stop) {
+    logger.info(`Stopping singleton service: ${name}`)
+    try {
+      await stop.call(service)
+    } catch (e: any) {
+      logger.error(`Error stopping service ${name}:`, e)
+    }
+  }
+}
+
+/**
+ * Stop all singleton services, including external package services.
+ * External package services are stopped first, then the parent services.
+ *
+ * @param singletonServices - The parent singleton services to stop
+ */
+export const stopSingletonServices = async (
+  singletonServices: CoreSingletonServices
+): Promise<void> => {
+  const logger = singletonServices.logger
+
+  // First, stop all external package singleton services
+  if (globalThis.pikkuState) {
+    for (const [packageName, packageState] of globalThis.pikkuState) {
+      // Skip main package - we handle it separately
+      if (packageName === '__main__') continue
+
+      const packageServices = packageState.package?.singletonServices
+      if (packageServices) {
+        logger.info(`Stopping singleton services for package: ${packageName}`)
+        for (const [name, service] of Object.entries(packageServices)) {
+          await stopService(logger, `${packageName}/${name}`, service)
+        }
+        // Clear the cached services
+        packageState.package.singletonServices = null
+      }
+    }
+  }
+
+  // Then stop the parent singleton services
+  for (const [name, service] of Object.entries(singletonServices)) {
+    await stopService(logger, name, service)
+  }
+}

package/src/wirings/channel/channel-common.ts

@@ -1,8 +1,4 @@
-import {
-  CoreServices,
-  PikkuWiringTypes,
-  CorePikkuMiddleware,
-} from '../../types/core.types.js'
+import { CoreServices, CorePikkuMiddleware } from '../../types/core.types.js'
 import { CoreChannel, ChannelMessageMeta } from './channel.types.js'
 import { combineMiddleware, runMiddleware } from '../../middleware-runner.js'
 import { runPikkuFuncDirectly } from '../../function/function-runner.js'
@@ -49,7 +45,7 @@ export const runChannelLifecycleWithMiddleware = async ({
 
   // Use combineMiddleware to properly resolve metadata + inline middleware
   const allMiddleware = combineMiddleware(
-    PikkuWiringTypes.channel,
+    'channel',
     `${channelConfig.name}:${lifecycleType}`,
     {
       wireInheritedMiddleware: meta.middleware,
@@ -61,7 +57,8 @@ export const runChannelLifecycleWithMiddleware = async ({
   const runLifecycle = async () => {
     return await runPikkuFuncDirectly(
       meta.pikkuFuncName,
-      { ...services, channel },
+      services,
+      { channel },
       data
     )
   }

package/src/wirings/channel/channel-handler.ts

@@ -2,7 +2,6 @@ import {
   CoreServices,
   JSONValue,
   CoreUserSession,
-  PikkuWiringTypes,
 } from '../../types/core.types.js'
 import {
   ChannelMessageMeta,
@@ -11,13 +10,14 @@ import {
 } from './channel.types.js'
 import { pikkuState } from '../../pikku-state.js'
 import { runPikkuFunc } from '../../function/function-runner.js'
+import { SessionService } from '../../services/user-session-service.js'
 
 const getRouteMeta = (
   channelName: string,
   routingProperty?: string,
   routerValue?: string
 ): ChannelMessageMeta => {
-  const channelMeta = pikkuState('channel', 'meta')[channelName]
+  const channelMeta = pikkuState(null, 'channel', 'meta')[channelName]
   if (!channelMeta) {
     throw new Error(`Channel ${channelName} not found`)
   }
@@ -62,7 +62,8 @@ const validateAuth = (
 export const processMessageHandlers = (
   services: CoreServices,
   channelConfig: CoreChannel<any, any>,
-  channelHandler: PikkuChannelHandler
+  channelHandler: PikkuChannelHandler,
+  userSession?: SessionService<CoreUserSession>
 ) => {
   const logger = services.logger
   const requiresSession = channelConfig.auth !== false
@@ -121,26 +122,19 @@ export const processMessageHandlers = (
       ? `${channelConfig.name}:${routingProperty}:${routerValue}`
       : `${channelConfig.name}:default`
 
-    return await runPikkuFunc(
-      PikkuWiringTypes.channel,
-      cacheKey,
-      pikkuFuncName,
-      {
-        singletonServices: services,
-        getAllServices: () => ({
-          ...services,
-          channel: channelHandler.getChannel(),
-        }),
-        data: () => data,
-        userSession: services.userSession,
-        inheritedMiddleware,
-        wireMiddleware,
-        inheritedPermissions,
-        wirePermissions,
-        tags: channelConfig.tags,
-        interaction: { channel: channelHandler.getChannel() },
-      }
-    )
+    return await runPikkuFunc('channel', cacheKey, pikkuFuncName, {
+      singletonServices: services,
+      data: () => data,
+      inheritedMiddleware,
+      wireMiddleware,
+      inheritedPermissions,
+      wirePermissions,
+      tags: channelConfig.tags,
+      wire: {
+        channel: channelHandler.getChannel(),
+        session: userSession,
+      },
+    })
   }
 
   return async (rawData): Promise<unknown> => {

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

@@ -3,7 +3,7 @@ import { addFunction } from '../../function/function-runner.js'
 import { CorePikkuPermission } from '../../function/functions.types.js'
 import { pikkuState } from '../../pikku-state.js'
 import { coerceTopLevelDataFromSchema, validateSchema } from '../../schema.js'
-import { UserSessionService } from '../../services/user-session-service.js'
+import { SessionService } from '../../services/user-session-service.js'
 import { CorePikkuMiddleware } from '../../types/core.types.js'
 import { httpRouter } from '../http/routers/http-router.js'
 import {
@@ -33,13 +33,13 @@ export const wireChannel = <
   >
 ) => {
   // Get the channel metadata
-  const channelsMeta = pikkuState('channel', 'meta')
+  const channelsMeta = pikkuState(null, 'channel', 'meta')
   const channelMeta = channelsMeta[channel.name]
   if (!channelMeta) {
     throw new Error(`Channel metadata not found for channel: ${channel.name}`)
   }
 
-  pikkuState('channel', 'channels').set(channel.name, channel as any)
+  pikkuState(null, 'channel', 'channels').set(channel.name, channel as any)
 
   // Register onConnect function if provided
   if (channel.onConnect && channelMeta.connect) {
@@ -89,7 +89,7 @@ export const wireChannel = <
   }
 
   // Store the channel configuration
-  pikkuState('channel', 'channels').set(channel.name, channel as any)
+  pikkuState(null, 'channel', 'channels').set(channel.name, channel as any)
 }
 
 const getMatchingChannelConfig = (path: string) => {
@@ -98,7 +98,7 @@ const getMatchingChannelConfig = (path: string) => {
     return null
   }
 
-  const meta = pikkuState('channel', 'meta')
+  const meta = pikkuState(null, 'channel', 'meta')
   const channelMeta = Object.values(meta).find(
     (channelConfig) => channelConfig.route === matchedPath.route
   )
@@ -106,7 +106,7 @@ const getMatchingChannelConfig = (path: string) => {
     return null
   }
 
-  const channels = pikkuState('channel', 'channels')
+  const channels = pikkuState(null, 'channel', 'channels')
   const channelConfig = channels.get(channelMeta.name)
   if (!channelConfig) {
     return null
@@ -128,7 +128,7 @@ export const openChannel = async ({
   request,
 }: Pick<CoreChannel<unknown, string>, 'route'> &
   RunChannelParams<unknown> & {
-    userSession: UserSessionService<any>
+    userSession: SessionService<any>
   } & RunChannelOptions): Promise<{
   openingData: unknown
   channelConfig: CoreChannel<unknown, any>