@pikku/core 0.12.4 → 0.12.6

package/src/pikku-state.ts

@@ -0,0 +1,216 @@
+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 type { AIAgentMeta } from './wirings/ai-agent/ai-agent.types.js'
+import type { GatewaysMeta } from './wirings/gateway/gateway.types.js'
+import type { ScheduledTasksMeta } from './wirings/scheduler/scheduler.types.js'
+import type { TriggerMeta } from './wirings/trigger/trigger.types.js'
+
+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 addon 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)
+ *
+ * // Addon 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 (!getAllPackageStates().has(resolvedPackageName)) {
+    initializePikkuState(resolvedPackageName)
+  }
+
+  const packageState = getAllPackageStates().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(),
+  },
+  addons: {
+    packages: new Map(),
+  },
+  http: {
+    middleware: new Map(),
+    permissions: new Map(),
+    routes: new Map(),
+    meta: {
+      post: {},
+      get: {},
+      delete: {},
+      patch: {},
+      head: {},
+      put: {},
+      options: {},
+    } as HTTPWiringsMeta,
+  },
+  channel: {
+    channels: new Map(),
+    meta: {},
+  },
+  scheduler: {
+    tasks: new Map(),
+    meta: [] as unknown as ScheduledTasksMeta,
+  },
+  queue: {
+    registrations: new Map(),
+    meta: {},
+  },
+  workflows: {
+    registrations: new Map(),
+    meta: {},
+  },
+  trigger: {
+    functions: new Map(),
+    triggers: new Map(),
+    triggerSources: new Map(),
+    meta: {} as TriggerMeta,
+    sourceMeta: {},
+  },
+  mcp: {
+    resources: new Map(),
+    resourcesMeta: {} as MCPResourceMeta,
+    toolsMeta: {} as MCPToolMeta,
+    prompts: new Map(),
+    promptsMeta: {} as MCPPromptMeta,
+  },
+  agent: {
+    agents: new Map(),
+    agentsMeta: {} as AIAgentMeta,
+  },
+  gateway: {
+    gateways: new Map(),
+    meta: {} as GatewaysMeta,
+  },
+  cli: {
+    meta: { programs: {}, renderers: {} },
+    programs: {},
+  },
+  middleware: {
+    tagGroup: {},
+    httpGroup: {},
+  },
+  channelMiddleware: {
+    tagGroup: {},
+  },
+  permissions: {
+    tagGroup: {},
+    httpGroup: {},
+  },
+  misc: {
+    errors: new Map(),
+    schemas: new Map(),
+    middleware: {},
+    channelMiddleware: {},
+    permissions: {},
+  },
+  models: {
+    config: null,
+  },
+  package: {
+    factories: null,
+    singletonServices: null,
+    metaDir: null,
+  },
+})
+
+/**
+ * Initialize state for a new package
+ */
+export const initializePikkuState = (packageName: string): void => {
+  if (!getAllPackageStates().has(packageName)) {
+    getAllPackageStates().set(packageName, createEmptyPackageState())
+  }
+}
+
+export const resetPikkuState = () => {
+  // Preserve the errors map before resetting
+  const existingErrors = getAllPackageStates().get('__main__')?.misc.errors
+
+  ;(globalThis as any)[PIKKU_STATE_KEY] = new Map<string, PikkuPackageState>()
+  initializePikkuState('__main__')
+
+  // Restore the errors map if it existed
+  if (existingErrors) {
+    const mainState = getAllPackageStates().get('__main__')!
+    mainState.misc.errors = existingErrors
+  }
+}
+
+if (!getAllPackageStates().has('__main__')) {
+  resetPikkuState()
+}
+
+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 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-addon')
+ * @param factories - The service factory functions
+ */
+export const addPackageServiceFactories = (
+  packageName: string,
+  factories: NonNullable<PikkuPackageState['package']['factories']>
+): void => {
+  pikkuState(packageName, 'package', 'factories', factories)
+}

package/src/run-tests-script.test.ts

@@ -0,0 +1,49 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+
+const thisDir = path.dirname(fileURLToPath(import.meta.url))
+const packageRoot = path.resolve(thisDir, '..')
+const runTestsScriptPath = path.join(packageRoot, 'run-tests.sh')
+
+describe('run-tests.sh discovery behavior', () => {
+  test('returns success by default when no tests are found', () => {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pikku-core-tests-'))
+    const srcDir = path.join(tempDir, 'src')
+    fs.mkdirSync(srcDir, { recursive: true })
+    fs.copyFileSync(runTestsScriptPath, path.join(tempDir, 'run-tests.sh'))
+
+    const result = spawnSync('bash', ['run-tests.sh'], {
+      cwd: tempDir,
+      encoding: 'utf8',
+      env: { ...process.env, CI: 'false' },
+    })
+
+    assert.equal(result.status, 0)
+    assert.match(result.stdout, /No test files found matching pattern/)
+
+    fs.rmSync(tempDir, { recursive: true, force: true })
+  })
+
+  test('returns failure in strict mode when no tests are found', () => {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pikku-core-tests-'))
+    const srcDir = path.join(tempDir, 'src')
+    fs.mkdirSync(srcDir, { recursive: true })
+    fs.copyFileSync(runTestsScriptPath, path.join(tempDir, 'run-tests.sh'))
+
+    const result = spawnSync('bash', ['run-tests.sh'], {
+      cwd: tempDir,
+      encoding: 'utf8',
+      env: { ...process.env, STRICT_TEST_DISCOVERY: '1' },
+    })
+
+    assert.equal(result.status, 1)
+    assert.match(result.stdout, /No test files found matching pattern/)
+
+    fs.rmSync(tempDir, { recursive: true, force: true })
+  })
+})

package/src/schema.test.ts

@@ -0,0 +1,249 @@
+import { test, describe, before, beforeEach } from 'node:test'
+import * as assert from 'assert'
+import {
+  addSchema,
+  getSchema,
+  coerceTopLevelDataFromSchema,
+  validateSchema,
+  compileAllSchemas,
+} from './schema.js'
+import { resetPikkuState } from './pikku-state.js'
+
+describe('Schema', () => {
+  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(() => {
+      addSchema('testSchema', {
+        properties: {
+          tags: { type: 'array' },
+          count: { type: 'number' },
+          name: { type: 'string' },
+        },
+      })
+
+      addSchema('booleanSchema', {
+        properties: {
+          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', () => {
+      const data = { tags: 'a,b,c' }
+      coerceTopLevelDataFromSchema('testSchema', data)
+      assert.deepStrictEqual(data.tags, ['a', 'b', 'c'])
+    })
+
+    test('should not modify properties of type array if they are already arrays', () => {
+      const data = { tags: ['a', 'b', 'c'] }
+      coerceTopLevelDataFromSchema('testSchema', data)
+      assert.deepStrictEqual(data.tags, ['a', 'b', 'c'])
+    })
+
+    test('should not modify properties that are not type array', () => {
+      const data = { count: 5, name: 'example' }
+      coerceTopLevelDataFromSchema('testSchema', data)
+      assert.strictEqual(data.count, 5)
+      assert.strictEqual(data.name, 'example')
+    })
+
+    test('should handle cases where the data object does not have a key present in the schema', () => {
+      const data = { unknownKey: 'shouldRemain' }
+      coerceTopLevelDataFromSchema('testSchema', data)
+      assert.strictEqual(data.unknownKey, 'shouldRemain')
+    })
+
+    test('should handle cases where schema properties contain boolean values', () => {
+      const data = { tags: 'a,b,c', isActive: 'true' }
+      coerceTopLevelDataFromSchema('booleanSchema', data)
+      assert.deepStrictEqual(data.tags, ['a', 'b', 'c'])
+      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

@@ -0,0 +1,151 @@
+import type { Logger } from './services/logger.js'
+import type { SchemaService } from './services/schema-service.js'
+import {
+  MissingSchemaError,
+  UnprocessableContentError,
+} from './errors/errors.js'
+import { pikkuState, getAllPackageStates } from './pikku-state.js'
+
+const schemaKey = (name: string, packageName: string | null): string =>
+  packageName ? `${packageName}:${name}` : name
+
+/**
+ * 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 addon packages).
+ * @ignore
+ */
+export const addSchema = (
+  name: string,
+  value: any,
+  packageName: string | null = null
+) => {
+  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 addon packages).
+ * @returns The schema value or undefined if not found.
+ * @ignore
+ */
+export const getSchema = (
+  name: string,
+  packageName: string | null = null
+): Record<string, unknown> | undefined => {
+  return pikkuState(packageName, 'misc', 'schemas').get(name)
+}
+
+/**
+ * Loads a schema and compiles it into a validator.
+ * @param logger - A logger for logging information.
+ */
+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 getAllPackageStates()) {
+    const resolvedPkgName = pkgName === '__main__' ? null : pkgName
+    for (const [name, schema] of packageState.misc.schemas) {
+      schemaService.compileSchema(schemaKey(name, resolvedPkgName), schema)
+    }
+  }
+  validateAllSchemasLoaded(logger, schemaService)
+}
+
+const validateAllSchemasLoaded = (
+  logger: Logger,
+  schemaService: SchemaService
+) => {
+  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(null, 'function', 'meta')[meta.pikkuFuncId]
+        ?.inputs
+      const input = inputs?.[0]
+      if (!input || validators.has(input)) {
+        continue
+      }
+      missingSchemas.push(input)
+    }
+  }
+
+  if (missingSchemas.length > 0) {
+    logger.error(
+      `Error: Failed to load schemas:\n.${missingSchemas.join('\n')}`
+    )
+    logger.error('\tHave you run the schema generation?')
+    logger.error('\tnpx @pikku/cli schemas')
+  } else {
+    logger.info('All schemas loaded')
+  }
+}
+
+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') {
+      continue
+    }
+    const type = property.type
+    if (typeof type === 'boolean') {
+      continue
+    }
+    if (type === 'array' && typeof data[key] === 'string') {
+      data[key] = data[key].split(',')
+    } else if (type === 'string' && property.format === 'date-time') {
+      data[key] = new Date(data[key])
+    }
+  }
+}
+
+export const validateSchema = async (
+  logger: Logger,
+  schemaService: SchemaService | undefined,
+  schemaName: string | undefined | null,
+  data: any,
+  packageName: string | null = null
+) => {
+  if (schemaService) {
+    if (!schemaName) {
+      if (data && (data.length > 0 || Object.keys(data).length > 0)) {
+        logger.warn('No schema provided, but data was passed')
+        throw new UnprocessableContentError('No data expected')
+      } else {
+        return
+      }
+    }
+    const key = schemaKey(schemaName, packageName)
+    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)'}`
+      )
+      throw new MissingSchemaError(
+        `Schema '${schemaName}' not found. Ensure schema generation has been run.`
+      )
+    }
+    await schemaService.compileSchema(key, schema)
+    await schemaService.validateSchema(key, data ?? {})
+  }
+}

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

@@ -0,0 +1,41 @@
+import type {
+  AIMessage,
+  AIAgentStep,
+  AIAgentToolDef,
+  AIStreamChannel,
+} from '../wirings/ai-agent/ai-agent.types.js'
+
+export type AIAgentRunnerParams = {
+  model: string
+  temperature?: number
+  instructions: string
+  messages: AIMessage[]
+  tools: AIAgentToolDef[]
+  maxSteps: number
+  toolChoice: 'auto' | 'required' | 'none'
+  outputSchema?: Record<string, unknown>
+}
+
+export type AIAgentRunnerResult = {
+  text: string
+  object?: unknown
+  steps: AIAgentStep[]
+  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<AIAgentStepResult>
+  run(params: AIAgentRunnerParams): Promise<AIAgentStepResult>
+}