@pikku/core 0.12.2 → 0.12.4

package/src/types/core.types.ts

@@ -1,470 +0,0 @@
-import type { Logger, LogLevel } from '../services/logger.js'
-import type { VariablesService } from '../services/variables-service.js'
-import type { SecretService } from '../services/secret-service.js'
-import type { SchemaService } from '../services/schema-service.js'
-import type { JWTService } from '../services/jwt-service.js'
-import type { PikkuHTTP } from '../wirings/http/http.types.js'
-import type {
-  PikkuChannel,
-  CorePikkuChannelMiddleware,
-  CorePikkuChannelMiddlewareFactory,
-} from '../wirings/channel/channel.types.js'
-import type { PikkuRPC } from '../wirings/rpc/rpc-types.js'
-import type { PikkuMCP } from '../wirings/mcp/mcp.types.js'
-import type { PikkuScheduledTask } from '../wirings/scheduler/scheduler.types.js'
-import type { PikkuQueue, QueueService } from '../wirings/queue/queue.types.js'
-import type { PikkuCLI } from '../wirings/cli/cli.types.js'
-import type {
-  PikkuWorkflowWire,
-  WorkflowService,
-  WorkflowServiceConfig,
-  WorkflowStepWire,
-} from '../wirings/workflow/workflow.types.js'
-import type { PikkuGraphWire } from '../wirings/workflow/graph/workflow-graph.types.js'
-import type { PikkuTrigger } from '../wirings/trigger/trigger.types.js'
-import type { PikkuGateway } from '../wirings/gateway/gateway.types.js'
-import type { SchedulerService } from '../services/scheduler-service.js'
-import type { DeploymentService } from '../services/deployment-service.js'
-import type { AIStorageService } from '../services/ai-storage-service.js'
-
-import type { ContentService } from '../services/content-service.js'
-import type { AIAgentRunnerService } from '../services/ai-agent-runner-service.js'
-import type { AIRunStateService } from '../services/ai-run-state-service.js'
-import type { PikkuAIMiddlewareHooks } from '../wirings/ai-agent/ai-agent.types.js'
-
-export type PikkuWiringTypes =
-  | 'http'
-  | 'scheduler'
-  | 'trigger'
-  | 'channel'
-  | 'rpc'
-  | 'queue'
-  | 'mcp'
-  | 'cli'
-  | 'workflow'
-  | 'agent'
-  | 'gateway'
-
-export interface FunctionServicesMeta {
-  optimized: boolean
-  services: string[]
-}
-
-export interface FunctionWiresMeta {
-  optimized: boolean
-  wires: string[]
-}
-
-/**
- * Metadata for middleware at any level
- * - type: 'http' = HTTP route middleware group (references httpGroup in pikkuState)
- * - type: 'tag' = Tag-based middleware group (references tagGroup in pikkuState)
- * - type: 'wire' = Wire-level individual middleware
- */
-export type MiddlewareMetadata =
-  | {
-      type: 'http'
-      route: string // Route pattern (e.g., '*' for all, '/api/*' for specific)
-    }
-  | {
-      type: 'tag'
-      tag: string // Tag name
-    }
-  | {
-      type: 'wire'
-      name: string
-      inline?: boolean // true if inline middleware
-    }
-
-/**
- * Metadata for permissions at any level
- * - type: 'http' = HTTP route permission group (references httpGroup in pikkuState)
- * - type: 'tag' = Tag-based permission group (references tagGroup in pikkuState)
- * - type: 'wire' = Wire-level individual permission
- */
-export type PermissionMetadata =
-  | {
-      type: 'http'
-      route: string // Route pattern (e.g., '*' for all, '/api/*' for specific)
-    }
-  | {
-      type: 'tag'
-      tag: string // Tag name
-    }
-  | {
-      type: 'wire'
-      name: string
-      inline?: boolean // true if inline permission
-    }
-
-export type FunctionRuntimeMeta = {
-  pikkuFuncId: string
-  inputSchemaName: string | null
-  outputSchemaName: string | null
-  expose?: boolean
-  remote?: boolean
-  mcp?: boolean
-  readonly?: boolean
-  sessionless?: boolean
-  version?: number
-  requiresApproval?: boolean
-  contractHash?: string
-  inputHash?: string
-  outputHash?: string
-}
-
-export type FunctionMeta = FunctionRuntimeMeta &
-  Partial<
-    {
-      name: string
-      functionType: 'user' | 'inline' | 'helper'
-      funcWrapper: string
-      services: FunctionServicesMeta
-      wires: FunctionWiresMeta
-      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>
-
-// Optimized runtime metadata with only essential fields
-
-export type MakeRequired<T, K extends keyof T> = Omit<T, K> &
-  Required<Pick<T, K>>
-
-/**
- * Represents a JSON primitive type which can be a string, number, boolean, null, or undefined.
- */
-export type JSONPrimitive = string | number | boolean | null | undefined
-
-/**
- * Represents a JSON value which can be a primitive, an array, or an object.
- */
-export type JSONValue =
-  | JSONPrimitive
-  | JSONValue[]
-  | {
-      [key: string]: JSONValue
-    }
-
-/**
- * Utility type for making certain keys required and leaving the rest as optional.
- */
-export type PickRequired<T, K extends keyof T> = Required<Pick<T, K>> &
-  Partial<T>
-
-/**
- * Utility type for making certain keys optional while keeping the rest required.
- */
-export type PickOptional<T, K extends keyof T> = Partial<T> & Pick<T, K>
-
-/**
- * Utility type that ensures at least one key in the given type `T` is required.
- */
-export type RequireAtLeastOne<T> = {
-  [K in keyof T]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<keyof T, K>>>
-}[keyof T]
-
-/**
- * Interface for the core configuration settings of Pikku.
- */
-export type CoreConfig<Config extends Record<string, unknown> = {}> = {
-  /** The log level for the application. */
-  logLevel?: LogLevel
-  /** Secrets used by the application (optional). */
-  secrets?: {}
-
-  workflow?: WorkflowServiceConfig
-} & Config
-
-/**
- * Represents a core user session, which can be extended for more specific session information.
- */
-export interface CoreUserSession {}
-
-/**
- * Interface for core singleton services provided by Pikku.
- */
-export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
-  /** The schema library used to validate data */
-  schema?: SchemaService
-  /** The JWT service used to encode and decode tokens */
-  jwt?: JWTService
-  /** The core configuration for the application. */
-  config: Config
-  /** The logger used by the application. */
-  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 */
-  queueService?: QueueService
-  /** The scheduler service */
-  schedulerService?: SchedulerService
-  /** The deployment service for service discovery */
-  deploymentService?: DeploymentService
-  /** AI agent storage service (threads, messages, working memory) */
-  aiStorage?: AIStorageService
-
-  /** Content service for file storage and retrieval */
-  content?: ContentService
-  /** AI agent runner service (model calls + tool loop) */
-  aiAgentRunner?: AIAgentRunnerService
-  /** AI run state service (run lifecycle + approval persistence) */
-  aiRunState?: AIRunStateService
-}
-
-/**
- * Represents different forms of wire within Pikku and the outside world.
- */
-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<{
-  wireType: PikkuWiringTypes
-  wireId: string
-  http: PikkuHTTP<In>
-  mcp: PikkuMCP<MCPTools>
-  rpc: TypedRPC
-  channel: [IsChannel] extends [null]
-    ? PikkuChannel<unknown, Out>
-    : PikkuChannel<unknown, Out> | undefined
-  scheduledTask: PikkuScheduledTask
-  queue: PikkuQueue
-  cli: PikkuCLI
-  workflow: TypedWorkflow
-  workflowStep: WorkflowStepWire
-  graph: PikkuGraphWire
-  trigger: PikkuTrigger<TriggerOutput>
-  gateway: PikkuGateway
-  session: HasInitialSession extends true
-    ? UserSession
-    : UserSession | undefined
-  /** Update and persist the current session */
-  setSession: (session: CoreUserSession) => Promise<void> | void
-  /** Clear and persist the current session */
-  clearSession: () => Promise<void> | void
-  /** Fetch the latest session (may read from backing store) */
-  getSession: () => Promise<UserSession> | UserSession | undefined
-  /** Whether the session was modified during this run */
-  hasSessionChanged: () => boolean
-}>
-
-/**
- * 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,
-  wires: PikkuWire<unknown, unknown, false, UserSession>,
-  next: () => Promise<void>
-) => Promise<void>
-
-/**
- * Configuration object for creating middleware with metadata
- *
- * @template SingletonServices - The singleton services type
- * @template UserSession - The user session type
- */
-export type CorePikkuMiddlewareConfig<
-  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
-  UserSession extends CoreUserSession = CoreUserSession,
-> = {
-  /** The middleware function */
-  func: CorePikkuMiddleware<SingletonServices, UserSession>
-  /** Optional human-readable name for the middleware */
-  name?: string
-  /** Optional description of what the middleware does */
-  description?: string
-}
-
-/**
- * A factory function that takes input and returns middleware
- * Used when middleware needs configuration/input parameters
- */
-export type CorePikkuMiddlewareFactory<
-  In = any,
-  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
-  UserSession extends CoreUserSession = CoreUserSession,
-> = (input: In) => CorePikkuMiddleware<SingletonServices, UserSession>
-
-/**
- * A group of middleware (combination of regular middleware and factories)
- * Used with addMiddleware() and addHTTPMiddleware() to group related middleware together
- */
-export type CorePikkuMiddlewareGroup<
-  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
-  UserSession extends CoreUserSession = CoreUserSession,
-> = Array<
-  | CorePikkuMiddleware<SingletonServices, UserSession>
-  | CorePikkuMiddlewareFactory<any, SingletonServices, UserSession>
->
-
-/**
- * Factory function for creating middleware with tree-shaking support
- * Supports both direct function and configuration object syntax
- *
- * @example
- * ```typescript
- * // Direct function syntax
- * export const logMiddleware = pikkuMiddleware(
- *   async ({ logger }, next) => {
- *     logger.info('Request started')
- *     await next()
- *   }
- * )
- *
- * // Configuration object syntax with metadata
- * export const logMiddleware = pikkuMiddleware({
- *   name: 'Request Logger',
- *   description: 'Logs request information',
- *   func: async ({ logger }, next) => {
- *     logger.info('Request started')
- *     await next()
- *   }
- * })
- * ```
- */
-export const pikkuMiddleware = <
-  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
-  UserSession extends CoreUserSession = CoreUserSession,
->(
-  middleware:
-    | CorePikkuMiddleware<SingletonServices, UserSession>
-    | CorePikkuMiddlewareConfig<SingletonServices, UserSession>
-): CorePikkuMiddleware<SingletonServices, UserSession> => {
-  return typeof middleware === 'function' ? middleware : middleware.func
-}
-
-/**
- * Factory function for creating middleware factories
- * Use this when your middleware needs configuration/input parameters
- *
- * @example
- * ```typescript
- * export const logMiddleware = pikkuMiddlewareFactory<LogOptions>(({
- *   message,
- *   level = 'info'
- * }) => {
- *   return pikkuMiddleware(async ({ logger }, next) => {
- *     logger[level](message)
- *     await next()
- *   })
- * })
- * ```
- */
-export const pikkuMiddlewareFactory = <In = any>(
-  factory: CorePikkuMiddlewareFactory<In>
-): CorePikkuMiddlewareFactory<In> => {
-  return factory
-}
-
-export const pikkuChannelMiddleware = <
-  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
-  Event = unknown,
->(
-  middleware: CorePikkuChannelMiddleware<SingletonServices, Event>
-): CorePikkuChannelMiddleware<SingletonServices, Event> => {
-  return middleware
-}
-
-export const pikkuChannelMiddlewareFactory = <In = any>(
-  factory: CorePikkuChannelMiddlewareFactory<In>
-): CorePikkuChannelMiddlewareFactory<In> => {
-  return factory
-}
-
-export type { PikkuAIMiddlewareHooks } from '../wirings/ai-agent/ai-agent.types.js'
-
-export const pikkuAIMiddleware = <
-  State extends Record<string, unknown> = Record<string, unknown>,
-  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
->(
-  hooks: PikkuAIMiddlewareHooks<State, SingletonServices>
-): PikkuAIMiddlewareHooks<State, SingletonServices> => hooks
-
-/**
- * Represents the core services used by Pikku, including singleton services.
- */
-export type CoreServices<SingletonServices = CoreSingletonServices> =
-  SingletonServices
-
-export type WireServices<
-  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
-  Services = CoreServices<SingletonServices>,
-> = Omit<Services, keyof SingletonServices | 'session'>
-
-/**
- * Defines a function type for creating singleton services from the given configuration.
- */
-export type CreateSingletonServices<
-  Config extends CoreConfig,
-  SingletonServices extends CoreSingletonServices,
-> = (
-  config: Config,
-  existingServices?: Partial<SingletonServices>
-) => Promise<SingletonServices>
-
-/**
- * Defines a function type for creating session-specific services.
- */
-export type CreateWireServices<
-  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
-  Services extends
-    CoreServices<SingletonServices> = CoreServices<SingletonServices>,
-  UserSession extends CoreUserSession = CoreUserSession,
-> = (
-  services: SingletonServices,
-  wire: PikkuWire<unknown, unknown, false, UserSession>
-) => Promise<WireServices<Services, SingletonServices>>
-
-/**
- * Defines a function type for creating config.
- */
-export type CreateConfig<
-  Config extends CoreConfig,
-  RemainingArgs extends any[] = unknown[],
-> = (variables?: VariablesService, ...args: RemainingArgs) => Promise<Config>
-
-/**
- * Represents the documentation for a route, including summary, description, tags, and errors.
- */
-export type CommonWireMeta = {
-  pikkuFuncId: string
-
-  title?: string
-  tags?: string[]
-  summary?: string
-  description?: string
-  errors?: string[]
-
-  middleware?: MiddlewareMetadata[]
-  permissions?: PermissionMetadata[]
-}
-
-/**
- * Serialized error for storage
- */
-export interface SerializedError {
-  message: string
-  stack?: string
-  code?: string
-  [key: string]: any
-}

package/src/types/state.types.ts

@@ -1,186 +0,0 @@
-import type { PikkuError, ErrorDetails } from '../errors/error-handler.js'
-import type {
-  CorePikkuFunctionConfig,
-  CorePermissionGroup,
-  CorePikkuPermission,
-} from '../function/functions.types.js'
-import type { CorePikkuTriggerFunctionConfig } from '../wirings/trigger/trigger.types.js'
-import type {
-  CoreChannel,
-  ChannelsMeta,
-} from '../wirings/channel/channel.types.js'
-import type { CLIMeta, CLIProgramState } from '../wirings/cli/cli.types.js'
-import type {
-  HTTPMethod,
-  CoreHTTPFunctionWiring,
-  HTTPWiringsMeta,
-} from '../wirings/http/http.types.js'
-import type {
-  CoreMCPResource,
-  MCPResourceMeta,
-  MCPToolMeta,
-  CoreMCPPrompt,
-  MCPPromptMeta,
-} from '../wirings/mcp/mcp.types.js'
-import type {
-  CoreAIAgent,
-  AIAgentMeta,
-} from '../wirings/ai-agent/ai-agent.types.js'
-import type {
-  CoreGateway,
-  GatewaysMeta,
-} from '../wirings/gateway/gateway.types.js'
-import type {
-  CoreQueueWorker,
-  QueueWorkersMeta,
-} from '../wirings/queue/queue.types.js'
-import type {
-  CoreScheduledTask,
-  ScheduledTasksMeta,
-} from '../wirings/scheduler/scheduler.types.js'
-import type {
-  CoreWorkflow,
-  WorkflowsRuntimeMeta,
-} from '../wirings/workflow/workflow.types.js'
-import type {
-  CoreTrigger,
-  CoreTriggerSource,
-  TriggerMeta,
-  TriggerSourceMeta,
-} from '../wirings/trigger/trigger.types.js'
-import type {
-  FunctionsMeta,
-  CorePikkuMiddleware,
-  CorePikkuMiddlewareGroup,
-  CreateConfig,
-  CreateSingletonServices,
-  CreateWireServices,
-  CoreConfig,
-  CoreSingletonServices,
-  CoreServices,
-  CoreUserSession,
-} from './core.types.js'
-import type { CorePikkuChannelMiddleware } from '../wirings/channel/channel.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 config (e.g., 'ext' -> { package: '@pikku/...', rpcEndpoint: '...' }) */
-    addons: Map<
-      string,
-      { package: string; rpcEndpoint?: string; auth?: boolean; tags?: 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>
-    meta: WorkflowsRuntimeMeta
-  }
-  trigger: {
-    functions: Map<string, CorePikkuTriggerFunctionConfig<any, any>>
-    triggers: Map<string, CoreTrigger>
-    triggerSources: Map<string, CoreTriggerSource>
-    meta: TriggerMeta
-    sourceMeta: TriggerSourceMeta
-  }
-  mcp: {
-    resources: Map<string, CoreMCPResource>
-    resourcesMeta: MCPResourceMeta
-    toolsMeta: MCPToolMeta
-    prompts: Map<string, CoreMCPPrompt>
-    promptsMeta: MCPPromptMeta
-  }
-  agent: {
-    agents: Map<string, CoreAIAgent>
-    agentsMeta: AIAgentMeta
-  }
-  gateway: {
-    gateways: Map<string, CoreGateway>
-    meta: GatewaysMeta
-  }
-  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>
-  }
-  channelMiddleware: {
-    tagGroup: Record<string, CorePikkuChannelMiddleware[]>
-  }
-  permissions: {
-    tagGroup: Record<string, CorePermissionGroup | CorePikkuPermission[]>
-    httpGroup: Record<string, CorePermissionGroup | CorePikkuPermission[]>
-  }
-  misc: {
-    errors: Map<PikkuError, ErrorDetails>
-    schemas: Map<string, any>
-    middleware: Record<string, CorePikkuMiddleware[]>
-    channelMiddleware: Record<string, CorePikkuChannelMiddleware[]>
-    permissions: Record<string, CorePermissionGroup | CorePikkuPermission[]>
-  }
-  models: {
-    config: {
-      models?: Record<
-        string,
-        string | { model: string; temperature?: number; maxSteps?: number }
-      >
-      agentDefaults?: { temperature?: number; maxSteps?: number }
-      agentOverrides?: Record<
-        string,
-        { model?: string; temperature?: number; maxSteps?: number }
-      >
-    } | null
-  }
-  package: {
-    /** Service factory functions for addon packages */
-    factories: {
-      createConfig?: CreateConfig<CoreConfig>
-      createSingletonServices?: CreateSingletonServices<
-        CoreConfig,
-        CoreSingletonServices
-      >
-      createWireServices?: CreateWireServices<
-        CoreSingletonServices,
-        CoreServices,
-        CoreUserSession
-      >
-    } | null
-    /** Cached singleton services for this package */
-    singletonServices: CoreSingletonServices | null
-    /** Absolute path to this package's .pikku directory */
-    metaDir: string | null
-  }
-}