@pikku/core 0.12.0 → 0.12.1

package/src/pikku-state.test.ts

@@ -0,0 +1,224 @@
+import { describe, test, beforeEach } from 'node:test'
+import assert from 'node:assert'
+import {
+  pikkuState,
+  resetPikkuState,
+  initializePikkuState,
+  getAllPackageStates,
+  getSingletonServices,
+  getCreateWireServices,
+  getPikkuMetaDir,
+  addPackageServiceFactories,
+} from './pikku-state.js'
+
+beforeEach(() => {
+  resetPikkuState()
+})
+
+describe('pikkuState', () => {
+  test('should get state for main package with null name', () => {
+    const functions = pikkuState(null, 'function', 'functions')
+    assert.ok(functions instanceof Map)
+  })
+
+  test('should get state for main package with __main__ name', () => {
+    const functions = pikkuState('__main__', 'function', 'functions')
+    assert.ok(functions instanceof Map)
+  })
+
+  test('should set and get state values', () => {
+    const testMeta = { key: 'value' }
+    pikkuState(null, 'function', 'meta', testMeta as any)
+    const result = pikkuState(null, 'function', 'meta')
+    assert.deepStrictEqual(result, testMeta)
+  })
+
+  test('should auto-initialize package state on first access', () => {
+    const states = getAllPackageStates()
+    assert.ok(!states.has('@test/package'))
+
+    pikkuState('@test/package', 'function', 'functions')
+
+    assert.ok(states.has('@test/package'))
+  })
+
+  test('should isolate state between packages', () => {
+    pikkuState(null, 'function', 'meta', { main: true } as any)
+    pikkuState('@addon/pkg', 'function', 'meta', { addon: true } as any)
+
+    assert.deepStrictEqual(pikkuState(null, 'function', 'meta'), { main: true })
+    assert.deepStrictEqual(pikkuState('@addon/pkg', 'function', 'meta'), {
+      addon: true,
+    })
+  })
+
+  test('should return correct state types', () => {
+    const httpRoutes = pikkuState(null, 'http', 'routes')
+    assert.ok(httpRoutes instanceof Map)
+
+    const schemas = pikkuState(null, 'misc', 'schemas')
+    assert.ok(schemas instanceof Map)
+
+    const errors = pikkuState(null, 'misc', 'errors')
+    assert.ok(errors instanceof Map)
+  })
+})
+
+describe('getAllPackageStates', () => {
+  test('should return a Map', () => {
+    const states = getAllPackageStates()
+    assert.ok(states instanceof Map)
+  })
+
+  test('should contain __main__ after reset', () => {
+    const states = getAllPackageStates()
+    assert.ok(states.has('__main__'))
+  })
+
+  test('should return same reference on multiple calls', () => {
+    const states1 = getAllPackageStates()
+    const states2 = getAllPackageStates()
+    assert.strictEqual(states1, states2)
+  })
+})
+
+describe('initializePikkuState', () => {
+  test('should create a new package state', () => {
+    const states = getAllPackageStates()
+    assert.ok(!states.has('@new/package'))
+
+    initializePikkuState('@new/package')
+
+    assert.ok(states.has('@new/package'))
+  })
+
+  test('should not overwrite existing package state', () => {
+    pikkuState('@existing/pkg', 'function', 'meta', { test: true } as any)
+
+    initializePikkuState('@existing/pkg')
+
+    const meta = pikkuState('@existing/pkg', 'function', 'meta')
+    assert.deepStrictEqual(meta, { test: true })
+  })
+})
+
+describe('resetPikkuState', () => {
+  test('should clear all package states', () => {
+    initializePikkuState('@addon/one')
+    initializePikkuState('@addon/two')
+    assert.ok(getAllPackageStates().has('@addon/one'))
+
+    resetPikkuState()
+
+    assert.ok(!getAllPackageStates().has('@addon/one'))
+    assert.ok(!getAllPackageStates().has('@addon/two'))
+  })
+
+  test('should preserve errors map from __main__', () => {
+    const errors = pikkuState(null, 'misc', 'errors')
+    errors.set('TestError', { status: 400, message: 'test' })
+
+    resetPikkuState()
+
+    const restoredErrors = pikkuState(null, 'misc', 'errors')
+    assert.strictEqual(restoredErrors.get('TestError')?.message, 'test')
+  })
+
+  test('should re-initialize __main__ package', () => {
+    resetPikkuState()
+
+    const states = getAllPackageStates()
+    assert.ok(states.has('__main__'))
+    assert.ok(pikkuState(null, 'function', 'functions') instanceof Map)
+  })
+
+  test('should create fresh state objects after reset', () => {
+    const functionsBefore = pikkuState(null, 'function', 'functions')
+    functionsBefore.set('testFunc', {} as any)
+
+    resetPikkuState()
+
+    const functionsAfter = pikkuState(null, 'function', 'functions')
+    assert.strictEqual(functionsAfter.size, 0)
+  })
+})
+
+describe('getSingletonServices', () => {
+  test('should throw when singleton services not initialized', () => {
+    assert.throws(() => getSingletonServices(), {
+      message: 'Singleton services not initialized',
+    })
+  })
+
+  test('should return services when initialized', () => {
+    const mockServices = { logger: { info: () => {} } }
+    pikkuState(null, 'package', 'singletonServices', mockServices as any)
+
+    const result = getSingletonServices()
+    assert.strictEqual(result, mockServices)
+  })
+})
+
+describe('getCreateWireServices', () => {
+  test('should return undefined when no factories set', () => {
+    const result = getCreateWireServices()
+    assert.strictEqual(result, undefined)
+  })
+
+  test('should return createWireServices when factories set', () => {
+    const mockCreateWire = async () => ({})
+    pikkuState(null, 'package', 'factories', {
+      createWireServices: mockCreateWire,
+    } as any)
+
+    const result = getCreateWireServices()
+    assert.strictEqual(result, mockCreateWire)
+  })
+})
+
+describe('getPikkuMetaDir', () => {
+  test('should return null by default', () => {
+    const result = getPikkuMetaDir()
+    assert.strictEqual(result, null)
+  })
+
+  test('should return metaDir when set', () => {
+    pikkuState(null, 'package', 'metaDir', '/some/path' as any)
+    const result = getPikkuMetaDir()
+    assert.strictEqual(result, '/some/path')
+  })
+
+  test('should return metaDir for specific package', () => {
+    pikkuState('@test/pkg', 'package', 'metaDir', '/addon/path' as any)
+    const result = getPikkuMetaDir('@test/pkg')
+    assert.strictEqual(result, '/addon/path')
+  })
+
+  test('should treat null packageName as main', () => {
+    pikkuState(null, 'package', 'metaDir', '/main/path' as any)
+    const result = getPikkuMetaDir(null)
+    assert.strictEqual(result, '/main/path')
+  })
+})
+
+describe('addPackageServiceFactories', () => {
+  test('should register factories for addon package', () => {
+    const mockFactories = {
+      createSingletonServices: async () => ({}),
+      createWireServices: async () => ({}),
+    }
+
+    addPackageServiceFactories('@addon/pkg', mockFactories as any)
+
+    const result = pikkuState('@addon/pkg', 'package', 'factories')
+    assert.strictEqual(result, mockFactories)
+  })
+
+  test('should not affect main package factories', () => {
+    const addonFactories = { createSingletonServices: async () => ({}) }
+    addPackageServiceFactories('@addon/pkg', addonFactories as any)
+
+    const mainFactories = pikkuState(null, 'package', 'factories')
+    assert.strictEqual(mainFactories, null)
+  })
+})

package/src/pikku-state.ts

@@ -1,23 +1,31 @@
-import { PikkuPackageState } from './index.js'
-import { HTTPWiringsMeta } from './wirings/http/http.types.js'
-import {
+import type { PikkuPackageState } from './index.js'
+import type {
+  CoreSingletonServices,
+  CreateWireServices,
+} from './types/core.types.js'
+import type { HTTPWiringsMeta } from './wirings/http/http.types.js'
+import type {
   MCPResourceMeta,
   MCPToolMeta,
   MCPPromptMeta,
 } from './wirings/mcp/mcp.types.js'
-import { AIAgentMeta } from './wirings/ai-agent/ai-agent.types.js'
-import { ScheduledTasksMeta } from './wirings/scheduler/scheduler.types.js'
-import { TriggerMeta } from './wirings/trigger/trigger.types.js'
+import type { AIAgentMeta } from './wirings/ai-agent/ai-agent.types.js'
+import type { ScheduledTasksMeta } from './wirings/scheduler/scheduler.types.js'
+import type { TriggerMeta } from './wirings/trigger/trigger.types.js'
 
-declare global {
-  // eslint-disable-next-line no-var
-  var pikkuState: Map<string, PikkuPackageState> | undefined
+const PIKKU_STATE_KEY = Symbol.for('@pikku/core/state')
+
+export const getAllPackageStates = (): Map<string, PikkuPackageState> => {
+  if (!(globalThis as any)[PIKKU_STATE_KEY]) {
+    ;(globalThis as any)[PIKKU_STATE_KEY] = new Map<string, PikkuPackageState>()
+  }
+  return (globalThis as any)[PIKKU_STATE_KEY] as Map<string, PikkuPackageState>
 }
 
 /**
  * Get or set package-scoped pikku state
  *
- * @param packageName - Package name (null for main package, '@scope/package' for external packages)
+ * @param packageName - Package name (null for main package, '@scope/package' for addon packages)
  * @param type - State category (function, rpc, http, etc.)
  * @param content - Content key within the category
  * @param value - Optional value to set
@@ -27,7 +35,7 @@ declare global {
  * // Main package
  * pikkuState(null, 'function', 'functions').get(funcName)
  *
- * // External package
+ * // Addon package
  * pikkuState('@acme/stripe-functions', 'rpc', 'meta')
  */
 export const pikkuState = <
@@ -42,14 +50,11 @@ export const pikkuState = <
   const resolvedPackageName = packageName ?? '__main__'
 
   // Initialize package state if it doesn't exist
-  if (
-    !globalThis.pikkuState ||
-    !globalThis.pikkuState.has(resolvedPackageName)
-  ) {
+  if (!getAllPackageStates().has(resolvedPackageName)) {
     initializePikkuState(resolvedPackageName)
   }
 
-  const packageState = globalThis.pikkuState!.get(resolvedPackageName)!
+  const packageState = getAllPackageStates().get(resolvedPackageName)!
 
   if (value !== undefined) {
     packageState[type][content] = value
@@ -66,7 +71,7 @@ const createEmptyPackageState = (): PikkuPackageState => ({
   rpc: {
     meta: {},
     files: new Map(),
-    externalPackages: new Map(),
+    addons: new Map(),
   },
   http: {
     middleware: new Map(),
@@ -152,29 +157,26 @@ const createEmptyPackageState = (): PikkuPackageState => ({
  * 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())
+  if (!getAllPackageStates().has(packageName)) {
+    getAllPackageStates().set(packageName, createEmptyPackageState())
   }
 }
 
 export const resetPikkuState = () => {
   // Preserve the errors map before resetting
-  const existingErrors = globalThis.pikkuState?.get('__main__')?.misc.errors
+  const existingErrors = getAllPackageStates().get('__main__')?.misc.errors
 
-  globalThis.pikkuState = new Map()
+  ;(globalThis as any)[PIKKU_STATE_KEY] = new Map<string, PikkuPackageState>()
   initializePikkuState('__main__')
 
   // Restore the errors map if it existed
   if (existingErrors) {
-    const mainState = globalThis.pikkuState.get('__main__')!
+    const mainState = getAllPackageStates().get('__main__')!
     mainState.misc.errors = existingErrors
   }
 }
 
-if (!globalThis.pikkuState) {
+if (!getAllPackageStates().has('__main__')) {
   resetPikkuState()
 }
 
@@ -182,11 +184,21 @@ export const getPikkuMetaDir = (packageName?: string | null): string | null => {
   return pikkuState(packageName ?? null, 'package', 'metaDir')
 }
 
+export const getSingletonServices = (): CoreSingletonServices => {
+  const services = pikkuState(null, 'package', 'singletonServices')
+  if (!services) throw new Error('Singleton services not initialized')
+  return services
+}
+
+export const getCreateWireServices = (): CreateWireServices | undefined => {
+  return pikkuState(null, 'package', 'factories')?.createWireServices
+}
+
 /**
- * Register service factories for an external package.
+ * Register service factories for an addon 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 packageName - The package name (e.g., '@pikku/templates-function-addon')
  * @param factories - The service factory functions
  */
 export const addPackageServiceFactories = (

package/src/schema.test.ts

@@ -1,11 +1,55 @@
-import { test, describe, before } from 'node:test'
+import { test, describe, before, beforeEach } from 'node:test'
 import * as assert from 'assert'
-import { addSchema, coerceTopLevelDataFromSchema } from './schema.js'
+import {
+  addSchema,
+  getSchema,
+  coerceTopLevelDataFromSchema,
+  validateSchema,
+  compileAllSchemas,
+} from './schema.js'
+import { resetPikkuState } from './pikku-state.js'
 
 describe('Schema', () => {
-  describe('coerceQueryStringToArray', () => {
+  describe('addSchema and getSchema', () => {
+    beforeEach(() => {
+      resetPikkuState()
+    })
+
+    test('should add and retrieve a schema', () => {
+      const schema = { properties: { name: { type: 'string' } } }
+      addSchema('testAdd', schema)
+      const result = getSchema('testAdd')
+      assert.deepStrictEqual(result, schema)
+    })
+
+    test('should return undefined for non-existent schema', () => {
+      const result = getSchema('nonExistent')
+      assert.strictEqual(result, undefined)
+    })
+
+    test('should add schema for specific package', () => {
+      const schema = { properties: { id: { type: 'number' } } }
+      addSchema('pkgSchema', schema, '@addon/pkg')
+      const result = getSchema('pkgSchema', '@addon/pkg')
+      assert.deepStrictEqual(result, schema)
+    })
+
+    test('should not find package schema in main', () => {
+      addSchema('pkgOnly', { properties: {} }, '@addon/pkg')
+      const result = getSchema('pkgOnly', null)
+      assert.strictEqual(result, undefined)
+    })
+
+    test('should unwrap default export', () => {
+      const schema = { default: { properties: { x: { type: 'string' } } } }
+      addSchema('withDefault', schema)
+      const result = getSchema('withDefault')
+      assert.deepStrictEqual(result, { properties: { x: { type: 'string' } } })
+    })
+  })
+
+  describe('coerceTopLevelDataFromSchema', () => {
     before(() => {
-      // Add schemas dynamically using addSchema
       addSchema('testSchema', {
         properties: {
           tags: { type: 'array' },
@@ -16,10 +60,16 @@ describe('Schema', () => {
 
       addSchema('booleanSchema', {
         properties: {
-          isActive: true, // Invalid schema definition, but the function should handle it
+          isActive: true,
           tags: { type: 'array' },
         },
       })
+
+      addSchema('dateSchema', {
+        properties: {
+          createdAt: { type: 'string', format: 'date-time' },
+        },
+      })
     })
 
     test('should split a string into an array for properties of type array', () => {
@@ -51,7 +101,149 @@ describe('Schema', () => {
       const data = { tags: 'a,b,c', isActive: 'true' }
       coerceTopLevelDataFromSchema('booleanSchema', data)
       assert.deepStrictEqual(data.tags, ['a', 'b', 'c'])
-      assert.strictEqual(data.isActive, 'true') // No coercion should happen
+      assert.strictEqual(data.isActive, 'true')
+    })
+
+    test('should coerce date-time strings to Date objects', () => {
+      const data = { createdAt: '2024-01-01T00:00:00Z' } as any
+      coerceTopLevelDataFromSchema('dateSchema', data)
+      assert.ok(data.createdAt instanceof Date)
+    })
+  })
+
+  describe('validateSchema', () => {
+    beforeEach(() => {
+      resetPikkuState()
+    })
+
+    test('should pass when no schema service provided', async () => {
+      const logger = {
+        info: () => {},
+        warn: () => {},
+        error: () => {},
+        debug: () => {},
+      } as any
+      await validateSchema(logger, undefined, 'some-schema', { data: 1 })
+    })
+
+    test('should warn when no schema name but data is passed', async () => {
+      let warningMsg = ''
+      const logger = {
+        info: () => {},
+        warn: (msg: string) => {
+          warningMsg = msg
+        },
+        error: () => {},
+        debug: () => {},
+      } as any
+      const schemaService = {
+        compileSchema: async () => {},
+        validateSchema: async () => {},
+        getSchemaNames: () => new Set<string>(),
+      }
+      await assert.rejects(
+        () => validateSchema(logger, schemaService, null, { key: 'value' }),
+        (err: any) => err.message === 'No data expected'
+      )
+    })
+
+    test('should return early when no schema name and empty data', async () => {
+      const logger = {
+        info: () => {},
+        warn: () => {},
+        error: () => {},
+        debug: () => {},
+      } as any
+      const schemaService = {
+        compileSchema: async () => {},
+        validateSchema: async () => {},
+        getSchemaNames: () => new Set<string>(),
+      }
+      await validateSchema(logger, schemaService, null, {})
+    })
+
+    test('should throw MissingSchemaError when schema not found', async () => {
+      const logger = {
+        info: () => {},
+        warn: () => {},
+        error: () => {},
+        debug: () => {},
+      } as any
+      const schemaService = {
+        compileSchema: async () => {},
+        validateSchema: async () => {},
+        getSchemaNames: () => new Set<string>(),
+      }
+      await assert.rejects(
+        () => validateSchema(logger, schemaService, 'nonExistent', { data: 1 }),
+        (err: any) => err.message.includes('not found')
+      )
+    })
+
+    test('should compile and validate schema when found', async () => {
+      addSchema('validSchema', { properties: { name: { type: 'string' } } })
+      const logger = {
+        info: () => {},
+        warn: () => {},
+        error: () => {},
+        debug: () => {},
+      } as any
+      let compiled = false
+      let validated = false
+      const schemaService = {
+        compileSchema: async () => {
+          compiled = true
+        },
+        validateSchema: async () => {
+          validated = true
+        },
+        getSchemaNames: () => new Set<string>(),
+      }
+      await validateSchema(logger, schemaService, 'validSchema', {
+        name: 'test',
+      })
+      assert.strictEqual(compiled, true)
+      assert.strictEqual(validated, true)
+    })
+  })
+
+  describe('compileAllSchemas', () => {
+    beforeEach(() => {
+      resetPikkuState()
+    })
+
+    test('should throw when no schema service available', () => {
+      const logger = {
+        info: () => {},
+        warn: () => {},
+        error: () => {},
+        debug: () => {},
+      } as any
+      assert.throws(() => compileAllSchemas(logger), {
+        message: 'SchemaService needs to be defined to load schemas',
+      })
+    })
+
+    test('should compile all schemas across packages', () => {
+      addSchema('schema1', { properties: { a: { type: 'string' } } })
+      addSchema('schema2', { properties: { b: { type: 'number' } } })
+
+      const compiled: string[] = []
+      const logger = {
+        info: () => {},
+        warn: () => {},
+        error: () => {},
+        debug: () => {},
+      } as any
+      const schemaService = {
+        compileSchema: (name: string, _schema: any) => {
+          compiled.push(name)
+        },
+        getSchemaNames: () => new Set(compiled),
+      }
+      compileAllSchemas(logger, schemaService as any)
+      assert.ok(compiled.includes('schema1'))
+      assert.ok(compiled.includes('schema2'))
     })
   })
 })

package/src/schema.ts

@@ -1,10 +1,10 @@
-import { Logger } from './services/logger.js'
-import { SchemaService } from './services/schema-service.js'
+import type { Logger } from './services/logger.js'
+import type { SchemaService } from './services/schema-service.js'
 import {
   MissingSchemaError,
   UnprocessableContentError,
 } from './errors/errors.js'
-import { pikkuState } from './pikku-state.js'
+import { pikkuState, getAllPackageStates } from './pikku-state.js'
 
 const schemaKey = (name: string, packageName: string | null): string =>
   packageName ? `${packageName}:${name}` : name
@@ -13,7 +13,7 @@ const schemaKey = (name: string, packageName: string | null): string =>
  * 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).
+ * @param packageName - The package name (null for main package, '@scope/package' for addon packages).
  * @ignore
  */
 export const addSchema = (
@@ -21,13 +21,14 @@ export const addSchema = (
   value: any,
   packageName: string | null = null
 ) => {
-  pikkuState(packageName, 'misc', 'schemas').set(name, value)
+  const schema = value?.default ?? value
+  pikkuState(packageName, 'misc', 'schemas').set(name, schema)
 }
 
 /**
  * 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).
+ * @param packageName - The package name (null for main package, '@scope/package' for addon packages).
  * @returns The schema value or undefined if not found.
  * @ignore
  */
@@ -46,10 +47,13 @@ export const compileAllSchemas = (
   logger: Logger,
   schemaService?: SchemaService
 ) => {
+  if (!schemaService) {
+    schemaService = pikkuState(null, 'package', 'singletonServices')?.schema
+  }
   if (!schemaService) {
     throw new Error('SchemaService needs to be defined to load schemas')
   }
-  for (const [pkgName, packageState] of globalThis.pikkuState!) {
+  for (const [pkgName, packageState] of getAllPackageStates()) {
     const resolvedPkgName = pkgName === '__main__' ? null : pkgName
     for (const [name, schema] of packageState.misc.schemas) {
       schemaService.compileSchema(schemaKey(name, resolvedPkgName), schema)

package/src/services/ai-agent-runner-service.ts

@@ -1,4 +1,4 @@
-import {
+import type {
   AIMessage,
   AIAgentStep,
   AIAgentToolDef,
@@ -23,7 +23,19 @@ export type AIAgentRunnerResult = {
   usage: { inputTokens: number; outputTokens: number }
 }
 
+export type AIAgentStepResult = {
+  text: string
+  object?: unknown
+  toolCalls: { toolCallId: string; toolName: string; args: unknown }[]
+  toolResults: { toolCallId: string; toolName: string; result: unknown }[]
+  usage: { inputTokens: number; outputTokens: number }
+  finishReason: 'stop' | 'tool-calls' | 'length' | 'error' | 'unknown'
+}
+
 export interface AIAgentRunnerService {
-  stream(params: AIAgentRunnerParams, channel: AIStreamChannel): Promise<void>
-  run(params: AIAgentRunnerParams): Promise<AIAgentRunnerResult>
+  stream(
+    params: AIAgentRunnerParams,
+    channel: AIStreamChannel
+  ): Promise<AIAgentStepResult>
+  run(params: AIAgentRunnerParams): Promise<AIAgentStepResult>
 }

package/src/services/ai-run-state-service.ts

@@ -1,4 +1,4 @@
-import {
+import type {
   AgentRunState,
   PendingApproval,
 } from '../wirings/ai-agent/ai-agent.types.js'

package/src/services/ai-storage-service.ts

@@ -1,4 +1,4 @@
-import { AIThread, AIMessage } from '../wirings/ai-agent/ai-agent.types.js'
+import type { AIThread, AIMessage } from '../wirings/ai-agent/ai-agent.types.js'
 
 export interface AIStorageService {
   createThread(