@pikku/core 0.12.4 → 0.12.6

package/src/types/state.types.ts

@@ -0,0 +1,188 @@
+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., 'console' -> { package: '@pikku/console', ... }) */
+  addons: {
+    packages: 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
+  }
+}

package/src/utils/hash.test.ts

@@ -0,0 +1,68 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { canonicalJSON, hashString } from './hash.js'
+
+describe('canonicalJSON', () => {
+  it('sorts object keys alphabetically', () => {
+    const result = canonicalJSON({ b: 1, a: 2, c: 3 })
+    assert.equal(result, '{"a":2,"b":1,"c":3}')
+  })
+
+  it('sorts nested object keys', () => {
+    const result = canonicalJSON({ z: { b: 1, a: 2 }, a: 1 })
+    assert.equal(result, '{"a":1,"z":{"a":2,"b":1}}')
+  })
+
+  it('preserves array order', () => {
+    const result = canonicalJSON([3, 1, 2])
+    assert.equal(result, '[3,1,2]')
+  })
+
+  it('sorts objects inside arrays', () => {
+    const result = canonicalJSON([{ b: 1, a: 2 }])
+    assert.equal(result, '[{"a":2,"b":1}]')
+  })
+
+  it('handles null and undefined', () => {
+    assert.equal(canonicalJSON(null), 'null')
+    assert.equal(canonicalJSON(undefined), undefined)
+  })
+
+  it('handles primitives', () => {
+    assert.equal(canonicalJSON('hello'), '"hello"')
+    assert.equal(canonicalJSON(42), '42')
+    assert.equal(canonicalJSON(true), 'true')
+  })
+
+  it('produces deterministic output for same input regardless of key order', () => {
+    const a = canonicalJSON({ x: 1, y: 2, z: 3 })
+    const b = canonicalJSON({ z: 3, x: 1, y: 2 })
+    assert.equal(a, b)
+  })
+})
+
+describe('hashString', () => {
+  it('returns a hex string of default length 16', () => {
+    const result = hashString('test')
+    assert.equal(result.length, 16)
+    assert.match(result, /^[0-9a-f]+$/)
+  })
+
+  it('returns consistent hash for same input', () => {
+    const a = hashString('hello world')
+    const b = hashString('hello world')
+    assert.equal(a, b)
+  })
+
+  it('returns different hashes for different inputs', () => {
+    const a = hashString('hello')
+    const b = hashString('world')
+    assert.notEqual(a, b)
+  })
+
+  it('respects custom length parameter', () => {
+    const result = hashString('test', 8)
+    assert.equal(result.length, 8)
+  })
+})

package/src/utils/hash.ts

@@ -0,0 +1,26 @@
+import { createHash } from 'crypto'
+
+export function canonicalJSON(obj: unknown): string {
+  return JSON.stringify(sortDeep(obj))
+}
+
+function sortDeep(value: unknown): unknown {
+  if (value === null || value === undefined) {
+    return value
+  }
+  if (Array.isArray(value)) {
+    return value.map(sortDeep)
+  }
+  if (typeof value === 'object') {
+    const sorted: Record<string, unknown> = {}
+    for (const key of Object.keys(value as Record<string, unknown>).sort()) {
+      sorted[key] = sortDeep((value as Record<string, unknown>)[key])
+    }
+    return sorted
+  }
+  return value
+}
+
+export function hashString(input: string, length: number = 16): string {
+  return createHash('sha256').update(input).digest('hex').slice(0, length)
+}

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)
+  })
+})