@pikku/core 0.11.2 → 0.12.1

package/src/types/state.types.ts

@@ -1,47 +1,53 @@
-import { PikkuError, ErrorDetails } from '../errors/error-handler.js'
-import {
+import type { PikkuError, ErrorDetails } from '../errors/error-handler.js'
+import type {
   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 {
+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 {
+import type {
   CoreMCPResource,
   MCPResourceMeta,
-  CoreMCPTool,
   MCPToolMeta,
   CoreMCPPrompt,
   MCPPromptMeta,
 } from '../wirings/mcp/mcp.types.js'
-import {
+import type {
+  CoreAIAgent,
+  AIAgentMeta,
+} from '../wirings/ai-agent/ai-agent.types.js'
+import type {
   CoreQueueWorker,
   QueueWorkersMeta,
 } from '../wirings/queue/queue.types.js'
-import {
+import type {
   CoreScheduledTask,
   ScheduledTasksMeta,
 } from '../wirings/scheduler/scheduler.types.js'
-import {
+import type {
   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 {
+  CoreTrigger,
+  CoreTriggerSource,
+  TriggerMeta,
+  TriggerSourceMeta,
+} from '../wirings/trigger/trigger.types.js'
+import type {
   FunctionsMeta,
   CorePikkuMiddleware,
   CorePikkuMiddlewareGroup,
-  FunctionServicesMeta,
   CreateConfig,
   CreateSingletonServices,
   CreateWireServices,
@@ -50,6 +56,7 @@ import {
   CoreServices,
   CoreUserSession,
 } from './core.types.js'
+import type { CorePikkuChannelMiddleware } from '../wirings/channel/channel.types.js'
 
 /**
  * State structure for an individual package
@@ -68,8 +75,11 @@ export interface PikkuPackageState {
         path: string
       }
     >
-    /** Maps namespace aliases to package names (e.g., 'ext' -> '@pikku/templates-function-external') */
-    externalPackages: Map<string, 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>[]>
@@ -91,28 +101,26 @@ export interface PikkuPackageState {
   }
   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: {
+    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
-    tools: Map<string, CoreMCPTool>
     toolsMeta: MCPToolMeta
     prompts: Map<string, CoreMCPPrompt>
     promptsMeta: MCPPromptMeta
   }
+  agent: {
+    agents: Map<string, CoreAIAgent>
+    agentsMeta: AIAgentMeta
+  }
   cli: {
     meta: CLIMeta | Record<string, any> // Backward compatible with old published CLI format
     programs: Record<string, CLIProgramState>
@@ -120,63 +128,36 @@ export interface PikkuPackageState {
   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
-      }
-    >
+  }
+  channelMiddleware: {
+    tagGroup: Record<string, CorePikkuChannelMiddleware[]>
   }
   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[]>
+    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 external packages */
+    /** Service factory functions for addon packages */
     factories: {
       createConfig?: CreateConfig<CoreConfig>
       createSingletonServices?: CreateSingletonServices<
@@ -191,5 +172,7 @@ export interface PikkuPackageState {
     } | null
     /** Cached singleton services for this package */
     singletonServices: CoreSingletonServices | null
+    /** Absolute path to this package's .pikku directory */
+    metaDir: string | null
   }
 }

package/src/utils.test.ts

@@ -0,0 +1,350 @@
+import { describe, test, beforeEach } from 'node:test'
+import assert from 'node:assert'
+import {
+  closeWireServices,
+  createWeakUID,
+  isSerializable,
+  getTagGroups,
+  freezeDedupe,
+  stopSingletonServices,
+} from './utils.js'
+import {
+  resetPikkuState,
+  pikkuState,
+  initializePikkuState,
+} from './pikku-state.js'
+
+beforeEach(() => {
+  resetPikkuState()
+})
+
+describe('createWeakUID', () => {
+  test('should return a string', () => {
+    const uid = createWeakUID()
+    assert.strictEqual(typeof uid, 'string')
+  })
+
+  test('should return unique values', () => {
+    const uid1 = createWeakUID()
+    const uid2 = createWeakUID()
+    assert.notStrictEqual(uid1, uid2)
+  })
+
+  test('should contain a dash separator', () => {
+    const uid = createWeakUID()
+    assert.ok(uid.includes('-'))
+  })
+})
+
+describe('isSerializable', () => {
+  test('should return true for objects', () => {
+    assert.strictEqual(isSerializable({ key: 'value' }), true)
+  })
+
+  test('should return true for arrays', () => {
+    assert.strictEqual(isSerializable([1, 2, 3]), true)
+  })
+
+  test('should return true for numbers', () => {
+    assert.strictEqual(isSerializable(42), true)
+  })
+
+  test('should return true for booleans', () => {
+    assert.strictEqual(isSerializable(true), true)
+  })
+
+  test('should return true for null', () => {
+    assert.strictEqual(isSerializable(null), true)
+  })
+
+  test('should return false for strings', () => {
+    assert.strictEqual(isSerializable('hello'), false)
+  })
+
+  test('should return false for ArrayBuffer', () => {
+    assert.strictEqual(isSerializable(new ArrayBuffer(8)), false)
+  })
+
+  test('should return false for Uint8Array', () => {
+    assert.strictEqual(isSerializable(new Uint8Array(8)), false)
+  })
+
+  test('should return false for Int8Array', () => {
+    assert.strictEqual(isSerializable(new Int8Array(8)), false)
+  })
+
+  test('should return false for Uint16Array', () => {
+    assert.strictEqual(isSerializable(new Uint16Array(8)), false)
+  })
+
+  test('should return false for Float64Array', () => {
+    assert.strictEqual(isSerializable(new Float64Array(8)), false)
+  })
+})
+
+describe('getTagGroups', () => {
+  test('should return exact match', () => {
+    const groups = { billing: 'billing-middleware' as any }
+    const result = getTagGroups(groups, 'billing')
+    assert.deepStrictEqual(result, ['billing-middleware'])
+  })
+
+  test('should return parent tag for namespaced tag', () => {
+    const groups = { billing: 'billing-middleware' as any }
+    const result = getTagGroups(groups, 'billing:read')
+    assert.deepStrictEqual(result, ['billing-middleware'])
+  })
+
+  test('should return both exact and parent matches', () => {
+    const groups = {
+      billing: 'billing-middleware' as any,
+      'billing:read': 'billing-read-middleware' as any,
+    }
+    const result = getTagGroups(groups, 'billing:read')
+    assert.deepStrictEqual(result, [
+      'billing-read-middleware',
+      'billing-middleware',
+    ])
+  })
+
+  test('should resolve multi-level namespace', () => {
+    const groups = {
+      billing: 'b' as any,
+      'billing:read': 'br' as any,
+      'billing:read:admin': 'bra' as any,
+    }
+    const result = getTagGroups(groups, 'billing:read:admin')
+    assert.deepStrictEqual(result, ['bra', 'br', 'b'])
+  })
+
+  test('should return empty array for unmatched tag', () => {
+    const groups = { billing: 'b' as any }
+    const result = getTagGroups(groups, 'other')
+    assert.deepStrictEqual(result, [])
+  })
+
+  test('should skip missing intermediate groups', () => {
+    const groups = {
+      billing: 'b' as any,
+      // no billing:read
+      'billing:read:admin': 'bra' as any,
+    }
+    const result = getTagGroups(groups, 'billing:read:admin')
+    assert.deepStrictEqual(result, ['bra', 'b'])
+  })
+})
+
+describe('freezeDedupe', () => {
+  test('should return frozen empty array for undefined', () => {
+    const result = freezeDedupe(undefined)
+    assert.strictEqual(result.length, 0)
+    assert.ok(Object.isFrozen(result))
+  })
+
+  test('should return frozen empty array for empty array', () => {
+    const result = freezeDedupe([])
+    assert.strictEqual(result.length, 0)
+    assert.ok(Object.isFrozen(result))
+  })
+
+  test('should return same frozen reference for empty arrays', () => {
+    const result1 = freezeDedupe([])
+    const result2 = freezeDedupe(undefined)
+    assert.strictEqual(result1, result2)
+  })
+
+  test('should return frozen single element array', () => {
+    const result = freezeDedupe(['a'])
+    assert.deepStrictEqual([...result], ['a'])
+    assert.ok(Object.isFrozen(result))
+  })
+
+  test('should deduplicate array', () => {
+    const a = () => {}
+    const b = () => {}
+    const result = freezeDedupe([a, b, a, b])
+    assert.strictEqual(result.length, 2)
+    assert.strictEqual(result[0], a)
+    assert.strictEqual(result[1], b)
+  })
+
+  test('should freeze the result', () => {
+    const result = freezeDedupe([1, 2, 3])
+    assert.ok(Object.isFrozen(result))
+  })
+
+  test('should preserve order (first occurrence)', () => {
+    const result = freezeDedupe([3, 1, 2, 1, 3])
+    assert.deepStrictEqual([...result], [3, 1, 2])
+  })
+})
+
+describe('closeWireServices', () => {
+  test('should call close on services that have it', async () => {
+    let closeCalled = false
+    const mockLogger = {
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+      debug: () => {},
+    }
+    const wireServices = {
+      serviceA: {
+        close: async () => {
+          closeCalled = true
+        },
+      },
+      serviceB: {},
+    }
+
+    await closeWireServices(mockLogger as any, wireServices as any)
+
+    assert.strictEqual(closeCalled, true)
+  })
+
+  test('should handle errors during close gracefully', async () => {
+    let errorLogged = false
+    const mockLogger = {
+      info: () => {},
+      warn: () => {},
+      error: () => {
+        errorLogged = true
+      },
+      debug: () => {},
+    }
+    const wireServices = {
+      serviceA: {
+        close: async () => {
+          throw new Error('close failed')
+        },
+      },
+    }
+
+    await closeWireServices(mockLogger as any, wireServices as any)
+
+    assert.strictEqual(errorLogged, true)
+  })
+
+  test('should skip services without close method', async () => {
+    const mockLogger = {
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+      debug: () => {},
+    }
+    const wireServices = {
+      serviceA: { doStuff: () => {} },
+      serviceB: null,
+    }
+
+    await closeWireServices(mockLogger as any, wireServices as any)
+    // Should not throw
+  })
+})
+
+describe('stopSingletonServices', () => {
+  test('should stop addon services first, then parent services', async () => {
+    const order: string[] = []
+    const mockServices = {
+      logger: {
+        info: () => {},
+        warn: () => {},
+        error: () => {},
+        debug: () => {},
+      },
+      serviceA: {
+        stop: async () => {
+          order.push('parent-serviceA')
+        },
+      },
+    }
+    pikkuState(null, 'package', 'singletonServices', mockServices as any)
+
+    initializePikkuState('@addon/pkg')
+    const addonServices = {
+      addonService: {
+        stop: async () => {
+          order.push('addon-addonService')
+        },
+      },
+    }
+    pikkuState(
+      '@addon/pkg',
+      'package',
+      'singletonServices',
+      addonServices as any
+    )
+
+    await stopSingletonServices()
+
+    assert.ok(
+      order.indexOf('addon-addonService') < order.indexOf('parent-serviceA')
+    )
+  })
+
+  test('should handle services without stop method', async () => {
+    const mockServices = {
+      logger: {
+        info: () => {},
+        warn: () => {},
+        error: () => {},
+        debug: () => {},
+      },
+      noStop: {},
+    }
+    pikkuState(null, 'package', 'singletonServices', mockServices as any)
+
+    await stopSingletonServices()
+    // Should not throw
+  })
+
+  test('should handle errors during stop gracefully', async () => {
+    let errorLogged = false
+    const mockServices = {
+      logger: {
+        info: () => {},
+        warn: () => {},
+        error: () => {
+          errorLogged = true
+        },
+        debug: () => {},
+      },
+      failing: {
+        stop: async () => {
+          throw new Error('stop failed')
+        },
+      },
+    }
+    pikkuState(null, 'package', 'singletonServices', mockServices as any)
+
+    await stopSingletonServices()
+
+    assert.strictEqual(errorLogged, true)
+  })
+
+  test('should clear addon singleton services after stopping', async () => {
+    const mockServices = {
+      logger: {
+        info: () => {},
+        warn: () => {},
+        error: () => {},
+        debug: () => {},
+      },
+    }
+    pikkuState(null, 'package', 'singletonServices', mockServices as any)
+
+    initializePikkuState('@addon/pkg')
+    pikkuState('@addon/pkg', 'package', 'singletonServices', {
+      s: { stop: async () => {} },
+    } as any)
+
+    await stopSingletonServices()
+
+    const addonServices = pikkuState(
+      '@addon/pkg',
+      'package',
+      'singletonServices'
+    )
+    assert.strictEqual(addonServices, null)
+  })
+})

package/src/utils.ts

@@ -1,15 +1,13 @@
-import { Logger } from './services/logger.js'
-import { CoreSingletonServices } from './types/core.types.js'
+import type { Logger } from './services/logger.js'
+import type { WireServices } from './types/core.types.js'
+import { getSingletonServices, getAllPackageStates } from './pikku-state.js'
 
-// TODO: WireServices probably needs it's own type
-// but is an issue for the future and will be tackled
-// with dependency injection
 export const closeWireServices = async (
   logger: Logger,
-  wireServices: Record<string, any>
+  wireServices: WireServices
 ) => {
   await Promise.all(
-    Object.values(wireServices).map(async (service) => {
+    Object.values(wireServices).map(async (service: any) => {
       if (service?.close) {
         try {
           await service.close()
@@ -21,9 +19,9 @@ export const closeWireServices = async (
   )
 }
 
-export const createWeakUID = () => {
-  return Date.now().toString(36) + Math.random().toString(36).substring(2, 10)
-}
+const _uidPrefix = Date.now().toString(36)
+let _uidCounter = 0
+export const createWeakUID = () => `${_uidPrefix}-${++_uidCounter}`
 
 export const isSerializable = (data: any): boolean => {
   return !(
@@ -40,6 +38,23 @@ export const isSerializable = (data: any): boolean => {
   )
 }
 
+export const getTagGroups = <T>(
+  tagGroups: Record<string, T>,
+  tag: string
+): T[] => {
+  const results: T[] = []
+  const exact = tagGroups[tag]
+  if (exact) results.push(exact)
+  let colonIdx = tag.lastIndexOf(':')
+  while (colonIdx !== -1) {
+    const parent = tag.slice(0, colonIdx)
+    const group = tagGroups[parent]
+    if (group) results.push(group)
+    colonIdx = parent.lastIndexOf(':')
+  }
+  return results
+}
+
 const EMPTY_ARRAY = Object.freeze([])
 
 export const freezeDedupe = <T>(
@@ -79,19 +94,19 @@ const stopService = async (
 }
 
 /**
- * Stop all singleton services, including external package services.
- * External package services are stopped first, then the parent services.
+ * Stop all singleton services, including addon package services.
+ * Addon 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> => {
+export const stopSingletonServices = async (): Promise<void> => {
+  const singletonServices = getSingletonServices()
   const logger = singletonServices.logger
 
-  // First, stop all external package singleton services
-  if (globalThis.pikkuState) {
-    for (const [packageName, packageState] of globalThis.pikkuState) {
+  // First, stop all addon package singleton services
+  const stateMap = getAllPackageStates()
+  if (stateMap.size > 0) {
+    for (const [packageName, packageState] of stateMap) {
       // Skip main package - we handle it separately
       if (packageName === '__main__') continue