@pikku/core 0.11.0 → 0.11.2

package/src/pikku-state.ts

@@ -1,230 +1,185 @@
-import { ChannelsMeta, CoreChannel } from './wirings/channel/channel.types.js'
+import { PikkuPackageState } from './index.js'
+import { HTTPWiringsMeta } from './wirings/http/http.types.js'
 import {
-  CoreHTTPFunctionWiring,
-  HTTPMethod,
-  HTTPWiringsMeta,
-} from './wirings/http/http.types.js'
-import {
-  FunctionsMeta,
-  CorePikkuMiddleware,
-  CorePikkuMiddlewareGroup,
-  FunctionServicesMeta,
-} from './types/core.types.js'
-import {
-  CoreScheduledTask,
-  ScheduledTasksMeta,
-} from './wirings/scheduler/scheduler.types.js'
-import { ErrorDetails, PikkuError } from './errors/error-handler.js'
-import {
-  CorePermissionGroup,
-  CorePikkuFunctionConfig,
-  CorePikkuPermission,
-} from './function/functions.types.js'
-import {
-  QueueWorkersMeta,
-  CoreQueueWorker,
-} from './wirings/queue/queue.types.js'
-import {
-  CoreMCPResource,
-  CoreMCPTool,
-  CoreMCPPrompt,
   MCPResourceMeta,
   MCPToolMeta,
   MCPPromptMeta,
 } from './wirings/mcp/mcp.types.js'
-import { CLIMeta, CLIProgramState } from './wirings/cli/cli.types.js'
-import {
-  CoreWorkflow,
-  WorkflowsMeta,
-} from './wirings/workflow/workflow.types.js'
+import { ScheduledTasksMeta } from './wirings/scheduler/scheduler.types.js'
+import { TriggerMeta } from './wirings/trigger/trigger.types.js'
 
-interface PikkuState {
-  function: {
-    meta: FunctionsMeta
-    functions: Map<string, CorePikkuFunctionConfig<any, any>>
+declare global {
+  // eslint-disable-next-line no-var
+  var pikkuState: Map<string, PikkuPackageState> | undefined
+}
+
+/**
+ * Get or set package-scoped pikku state
+ *
+ * @param packageName - Package name (null for main package, '@scope/package' for external packages)
+ * @param type - State category (function, rpc, http, etc.)
+ * @param content - Content key within the category
+ * @param value - Optional value to set
+ * @returns The current value of the state
+ *
+ * @example
+ * // Main package
+ * pikkuState(null, 'function', 'functions').get(funcName)
+ *
+ * // External package
+ * pikkuState('@acme/stripe-functions', 'rpc', 'meta')
+ */
+export const pikkuState = <
+  Type extends keyof PikkuPackageState,
+  Content extends keyof PikkuPackageState[Type],
+>(
+  packageName: string | null,
+  type: Type,
+  content: Content,
+  value?: PikkuPackageState[Type][Content]
+): PikkuPackageState[Type][Content] => {
+  const resolvedPackageName = packageName ?? '__main__'
+
+  // Initialize package state if it doesn't exist
+  if (
+    !globalThis.pikkuState ||
+    !globalThis.pikkuState.has(resolvedPackageName)
+  ) {
+    initializePikkuState(resolvedPackageName)
   }
-  rpc: {
-    meta: Record<string, string>
-    files: Map<
-      string,
-      {
-        exportedName: string
-        path: string
-      }
-    >
+
+  const packageState = globalThis.pikkuState!.get(resolvedPackageName)!
+
+  if (value !== undefined) {
+    packageState[type][content] = value
   }
+
+  return packageState[type][content]
+}
+
+const createEmptyPackageState = (): PikkuPackageState => ({
+  function: {
+    meta: {},
+    functions: new Map(),
+  },
+  rpc: {
+    meta: {},
+    files: new Map(),
+    externalPackages: new Map(),
+  },
   http: {
-    middleware: Map<string, CorePikkuMiddleware<any, any>[]>
-    permissions: Map<string, CorePermissionGroup | CorePikkuPermission[]>
-    routes: Map<HTTPMethod, Map<string, CoreHTTPFunctionWiring<any, any, any>>>
-    meta: HTTPWiringsMeta
-  }
+    middleware: new Map(),
+    permissions: new Map(),
+    routes: new Map(),
+    meta: {
+      post: {},
+      get: {},
+      delete: {},
+      patch: {},
+      head: {},
+      put: {},
+      options: {},
+    } as HTTPWiringsMeta,
+  },
   channel: {
-    channels: Map<string, CoreChannel<any, any>>
-    meta: ChannelsMeta
-  }
+    channels: new Map(),
+    meta: {},
+  },
   scheduler: {
-    tasks: Map<string, CoreScheduledTask>
-    meta: ScheduledTasksMeta
-  }
+    tasks: new Map(),
+    meta: [] as unknown as ScheduledTasksMeta,
+  },
   queue: {
-    registrations: Map<string, CoreQueueWorker>
-    meta: QueueWorkersMeta
-  }
+    registrations: new Map(),
+    meta: {},
+  },
   workflows: {
-    registrations: Map<string, CoreWorkflow>
-    meta: WorkflowsMeta
-  }
+    registrations: new Map(),
+    graphRegistrations: new Map(),
+    wirings: new Map(),
+    graphWirings: new Map(),
+    meta: {},
+  },
+  trigger: {
+    triggers: new Map(),
+    meta: {} as TriggerMeta,
+  },
   mcp: {
-    resources: Map<string, CoreMCPResource>
-    resourcesMeta: MCPResourceMeta
-    tools: Map<string, CoreMCPTool>
-    toolsMeta: MCPToolMeta
-    prompts: Map<string, CoreMCPPrompt>
-    promptsMeta: MCPPromptMeta
-  }
+    resources: new Map(),
+    resourcesMeta: {} as MCPResourceMeta,
+    tools: new Map(),
+    toolsMeta: {} as MCPToolMeta,
+    prompts: new Map(),
+    promptsMeta: {} as MCPPromptMeta,
+  },
   cli: {
-    meta: CLIMeta | Record<string, any> // Backward compatible with old published CLI format
-    programs: Record<string, CLIProgramState>
-  }
+    meta: { programs: {}, renderers: {} },
+    programs: {},
+  },
   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
-      }
-    >
-  }
+    tagGroup: {},
+    httpGroup: {},
+    tagGroupMeta: {},
+    httpGroupMeta: {},
+  },
   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
-      }
-    >
-  }
+    tagGroup: {},
+    httpGroup: {},
+    tagGroupMeta: {},
+    httpGroupMeta: {},
+  },
   misc: {
-    errors: Map<PikkuError, ErrorDetails>
-    schemas: Map<string, any>
-    middleware: Record<string, CorePikkuMiddleware[]>
-    permissions: Record<string, CorePermissionGroup | CorePikkuPermission[]>
+    errors: new Map(),
+    schemas: new Map(),
+    middleware: {},
+    permissions: {},
+  },
+  package: {
+    factories: null,
+    singletonServices: null,
+  },
+})
+
+/**
+ * Initialize state for a new package
+ */
+export const initializePikkuState = (packageName: string): void => {
+  if (!globalThis.pikkuState) {
+    globalThis.pikkuState = new Map()
+  }
+  if (!globalThis.pikkuState.has(packageName)) {
+    globalThis.pikkuState.set(packageName, createEmptyPackageState())
   }
 }
 
 export const resetPikkuState = () => {
-  globalThis.pikkuState = {
-    function: {
-      meta: {},
-      functions: new Map(),
-    },
-    rpc: {
-      meta: {},
-      files: new Map(),
-    },
-    http: {
-      permissions: new Map(),
-      routes: new Map(),
-      meta: {},
-    },
-    channel: {
-      channels: new Map(),
-      meta: {},
-    },
-    scheduler: {
-      tasks: new Map(),
-      meta: [] as unknown as ScheduledTasksMeta,
-    },
-    queue: {
-      registrations: new Map(),
-      meta: {},
-    },
-    workflows: {
-      registrations: new Map(),
-      meta: {},
-    },
-    mcp: {
-      resources: new Map(),
-      resourcesMeta: {} as MCPResourceMeta,
-      tools: new Map(),
-      toolsMeta: {} as MCPToolMeta,
-      prompts: new Map(),
-      promptsMeta: {} as MCPPromptMeta,
-    },
-    cli: {
-      meta: { programs: {}, renderers: {} },
-      programs: {},
-    },
-    middleware: {
-      tagGroup: {},
-      httpGroup: {},
-      tagGroupMeta: {},
-      httpGroupMeta: {},
-    },
-    permissions: {
-      tagGroup: {},
-      httpGroup: {},
-      tagGroupMeta: {},
-      httpGroupMeta: {},
-    },
-    misc: {
-      errors: globalThis.pikkuState?.misc?.errors || new Map(),
-      schemas: new Map(),
-      middleware: {},
-      permissions: {},
-    },
-  } as PikkuState
+  // Preserve the errors map before resetting
+  const existingErrors = globalThis.pikkuState?.get('__main__')?.misc.errors
+
+  globalThis.pikkuState = new Map()
+  initializePikkuState('__main__')
+
+  // Restore the errors map if it existed
+  if (existingErrors) {
+    const mainState = globalThis.pikkuState.get('__main__')!
+    mainState.misc.errors = existingErrors
+  }
 }
 
 if (!globalThis.pikkuState) {
   resetPikkuState()
 }
 
-export const pikkuState = <
-  Type extends keyof PikkuState,
-  Content extends keyof PikkuState[Type],
->(
-  type: Type,
-  content: Content,
-  value?: PikkuState[Type][Content]
-): PikkuState[Type][Content] => {
-  if (value) {
-    globalThis.pikkuState[type][content] = value
-  }
-  return globalThis.pikkuState[type][content]
+/**
+ * Register service factories for an external package.
+ * These factories are used to create services when the package's functions are invoked.
+ *
+ * @param packageName - The package name (e.g., '@pikku/templates-function-external')
+ * @param factories - The service factory functions
+ */
+export const addPackageServiceFactories = (
+  packageName: string,
+  factories: NonNullable<PikkuPackageState['package']['factories']>
+): void => {
+  pikkuState(packageName, 'package', 'factories', factories)
 }

package/src/schema.ts

@@ -4,25 +4,32 @@ import { UnprocessableContentError } from './errors/errors.js'
 import { pikkuState } from './pikku-state.js'
 
 /**
- * Adds a schema to the global schemas map.
+ * Adds a schema to the schemas map for a specific package.
  * @param name - The name of the schema.
  * @param value - The schema value.
+ * @param packageName - The package name (null for main package, '@scope/package' for external packages).
  * @ignore
  */
-export const addSchema = (name: string, value: any) => {
-  pikkuState('misc', 'schemas').set(name, value)
+export const addSchema = (
+  name: string,
+  value: any,
+  packageName: string | null = null
+) => {
+  pikkuState(packageName, 'misc', 'schemas').set(name, value)
 }
 
 /**
- * Retrieves a schema from the global schemas map.
+ * Retrieves a schema from the schemas map for a specific package.
  * @param name - The name of the schema.
+ * @param packageName - The package name (null for main package, '@scope/package' for external packages).
  * @returns The schema value or undefined if not found.
  * @ignore
  */
 export const getSchema = (
-  name: string
+  name: string,
+  packageName: string | null = null
 ): Record<string, unknown> | undefined => {
-  return pikkuState('misc', 'schemas').get(name)
+  return pikkuState(packageName, 'misc', 'schemas').get(name)
 }
 
 /**
@@ -36,7 +43,7 @@ export const compileAllSchemas = (
   if (!schemaService) {
     throw new Error('SchemaService needs to be defined to load schemas')
   }
-  const schemas = pikkuState('misc', 'schemas')
+  const schemas = pikkuState(null, 'misc', 'schemas')
   for (const [name, schema] of schemas) {
     schemaService.compileSchema(name, schema)
   }
@@ -47,14 +54,15 @@ const validateAllSchemasLoaded = (
   logger: Logger,
   schemaService: SchemaService
 ) => {
-  const routesMeta = pikkuState('http', 'meta')
+  const routesMeta = pikkuState(null, 'http', 'meta')
   const validators = schemaService.getSchemaNames()
 
   const missingSchemas: string[] = []
 
   for (const routePaths of Object.values(routesMeta)) {
     for (const meta of Object.values(routePaths)) {
-      const inputs = pikkuState('function', 'meta')[meta.pikkuFuncName]?.inputs
+      const inputs = pikkuState(null, 'function', 'meta')[meta.pikkuFuncName]
+        ?.inputs
       const input = inputs?.[0]
       if (!input || validators.has(input)) {
         continue
@@ -74,8 +82,12 @@ const validateAllSchemasLoaded = (
   }
 }
 
-export const coerceTopLevelDataFromSchema = (schemaName: string, data: any) => {
-  const schema = pikkuState('misc', 'schemas').get(schemaName)
+export const coerceTopLevelDataFromSchema = (
+  schemaName: string,
+  data: any,
+  packageName: string | null = null
+) => {
+  const schema = pikkuState(packageName, 'misc', 'schemas').get(schemaName)
   for (const key in schema.properties) {
     const property = schema.properties[key]
     if (typeof property === 'boolean') {
@@ -97,7 +109,8 @@ export const validateSchema = async (
   logger: Logger,
   schemaService: SchemaService | undefined,
   schemaName: string | undefined | null,
-  data: any
+  data: any,
+  packageName: string | null = null
 ) => {
   if (schemaService) {
     if (!schemaName) {
@@ -108,7 +121,23 @@ export const validateSchema = async (
         return
       }
     }
-    const schema = pikkuState('misc', 'schemas').get(schemaName)
+    logger.debug(
+      `[validateSchema] Validating schema '${schemaName}' for package '${packageName ?? 'main'}' with data:`,
+      JSON.stringify(data)
+    )
+    const schemas = pikkuState(packageName, 'misc', 'schemas')
+    const schema = schemas.get(schemaName)
+    if (schema === undefined) {
+      const availableSchemas = Array.from(schemas.keys())
+      logger.error(
+        `Schema '${schemaName}' not found for package '${packageName ?? 'main'}'. Available schemas: ${availableSchemas.join(', ') || '(none)'}`
+      )
+    } else {
+      logger.debug(
+        `[validateSchema] Found schema '${schemaName}':`,
+        JSON.stringify(schema)
+      )
+    }
     await schemaService.compileSchema(schemaName, schema)
     await schemaService.validateSchema(schemaName, data)
   }

package/src/services/user-session-service.ts

@@ -1,18 +1,21 @@
 import { ChannelStore } from '../wirings/channel/channel-store.js'
 import { CoreUserSession } from '../types/core.types.js'
 
-export interface UserSessionService<UserSession extends CoreUserSession> {
+export interface SessionService<UserSession extends CoreUserSession> {
   sessionChanged: boolean
+  initial: UserSession | undefined
   setInitial(session: UserSession): void
+  freezeInitial(): UserSession | undefined
   set(session: UserSession): Promise<void> | void
   clear(): Promise<void> | void
-  get(): Promise<UserSession | undefined> | UserSession | undefined
+  get(): Promise<UserSession> | UserSession | undefined
 }
 
-export class PikkuUserSessionService<UserSession extends CoreUserSession>
-  implements UserSessionService<UserSession>
+export class PikkuSessionService<UserSession extends CoreUserSession>
+  implements SessionService<UserSession>
 {
   public sessionChanged = false
+  public initial: UserSession | undefined
   private session: UserSession | undefined
   constructor(
     private channelStore?: ChannelStore<unknown, unknown, UserSession>,
@@ -27,6 +30,13 @@ export class PikkuUserSessionService<UserSession extends CoreUserSession>
     this.session = session
   }
 
+  public freezeInitial() {
+    if (this.initial === undefined) {
+      this.initial = this.session
+    }
+    return this.initial
+  }
+
   public set(session: UserSession) {
     this.sessionChanged = true
     this.session = session

package/src/services/workflow-service.ts

@@ -0,0 +1,74 @@
+import {
+  SerializedError,
+  CoreSingletonServices,
+  CreateWireServices,
+  CoreConfig,
+} from '../types/core.types.js'
+import {
+  WorkflowRun,
+  StepState,
+  WorkflowStatus,
+} from '../wirings/workflow/workflow.types.js'
+
+/**
+ * Interface for workflow orchestration
+ * Handles workflow execution, replay, orchestration logic, and run-level state
+ */
+export interface WorkflowService {
+  // Run-level state operations
+  createRun(workflowName: string, input: any, inline?: boolean): Promise<string>
+  getRun(id: string): Promise<WorkflowRun | null>
+  getRunHistory(runId: string): Promise<Array<StepState & { stepName: string }>>
+  updateRunStatus(
+    id: string,
+    status: WorkflowStatus,
+    output?: any,
+    error?: SerializedError
+  ): Promise<void>
+  withRunLock<T>(id: string, fn: () => Promise<T>): Promise<T>
+  close(): Promise<void>
+
+  // Orchestration operations
+  resumeWorkflow(runId: string): Promise<void>
+  setServices(
+    singletonServices: CoreSingletonServices,
+    createWireServices: CreateWireServices,
+    config: CoreConfig
+  ): void
+  startWorkflow<I>(
+    name: string,
+    input: I,
+    rpcService: any,
+    options?: { inline?: boolean; startNode?: string }
+  ): Promise<{ runId: string }>
+  runWorkflowJob(runId: string, rpcService: any): Promise<void>
+  orchestrateWorkflow(runId: string, rpcService: any): Promise<void>
+  executeWorkflowSleepCompleted(runId: string, stepId: string): Promise<void>
+
+  // Step-level state operations
+  insertStepState(
+    runId: string,
+    stepName: string,
+    rpcName: string,
+    data: any,
+    stepOptions?: { retries?: number; retryDelay?: string | number }
+  ): Promise<StepState>
+  getStepState(runId: string, stepName: string): Promise<StepState>
+  setStepRunning(stepId: string): Promise<void>
+  setStepScheduled(stepId: string): Promise<void>
+  setStepResult(stepId: string, result: any): Promise<void>
+  setStepError(stepId: string, error: Error): Promise<void>
+  createRetryAttempt(
+    stepId: string,
+    status: 'pending' | 'running'
+  ): Promise<StepState>
+
+  // Step execution
+  executeWorkflowStep(
+    runId: string,
+    stepName: string,
+    rpcName: string | null,
+    data: any,
+    rpcService: any
+  ): Promise<void>
+}