@pikku/core 0.12.4 → 0.12.5

package/src/services/local-gateway-service.ts

@@ -0,0 +1,62 @@
+import type { GatewayService } from './gateway-service.js'
+import type { GatewayAdapter } from '../wirings/gateway/gateway.types.js'
+import { pikkuState, getSingletonServices } from '../pikku-state.js'
+import { createListenerMessageHandler } from '../wirings/gateway/gateway-runner.js'
+
+/**
+ * Local GatewayService implementation.
+ *
+ * Starts all registered listener gateways unconditionally (single-process).
+ * For distributed deployments, implement `GatewayService` with leader
+ * election or similar coordination.
+ *
+ * @example
+ * ```typescript
+ * const gatewayService = new LocalGatewayService()
+ * await gatewayService.start()
+ *
+ * // On shutdown
+ * await gatewayService.stop()
+ * ```
+ */
+export class LocalGatewayService implements GatewayService {
+  private activeAdapters = new Map<string, GatewayAdapter>()
+
+  async start(): Promise<void> {
+    const singletonServices = getSingletonServices()
+    const gateways = pikkuState(null, 'gateway', 'gateways')
+
+    for (const [name, config] of gateways) {
+      if (config.type !== 'listener') continue
+      if (this.activeAdapters.has(name)) continue
+
+      const handleMessage = createListenerMessageHandler(
+        name,
+        config,
+        singletonServices
+      )
+
+      await config.adapter.init(handleMessage)
+      this.activeAdapters.set(name, config.adapter)
+      singletonServices.logger.info(`Started listener gateway: ${name}`)
+    }
+  }
+
+  async stop(): Promise<void> {
+    for (const [name, adapter] of this.activeAdapters) {
+      try {
+        await adapter.close()
+      } catch (e: any) {
+        try {
+          getSingletonServices().logger.error(
+            `Error closing listener gateway '${name}':`,
+            e
+          )
+        } catch {
+          // logger may not be available during shutdown
+        }
+      }
+    }
+    this.activeAdapters.clear()
+  }
+}

package/src/services/local-secrets.test.ts

@@ -0,0 +1,80 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert'
+import { LocalSecretService } from './local-secrets.js'
+import { LocalVariablesService } from './local-variables.js'
+
+describe('LocalSecretService', () => {
+  test('should get secret from local storage', async () => {
+    const service = new LocalSecretService()
+    await service.setSecretJSON('MY_KEY', { token: 'abc' })
+    const result = await service.getSecret('MY_KEY')
+    assert.strictEqual(result, '{"token":"abc"}')
+  })
+
+  test('should get secret from environment variables', async () => {
+    const vars = new LocalVariablesService({ MY_SECRET: 'secret-value' })
+    const service = new LocalSecretService(vars)
+    const result = await service.getSecret('MY_SECRET')
+    assert.strictEqual(result, 'secret-value')
+  })
+
+  test('should throw when secret not found', async () => {
+    const vars = new LocalVariablesService({})
+    const service = new LocalSecretService(vars)
+    await assert.rejects(() => service.getSecret('MISSING'), {
+      message: 'Secret Not Found: MISSING',
+    })
+  })
+
+  test('should get JSON secret from local storage', async () => {
+    const service = new LocalSecretService()
+    await service.setSecretJSON('JSON_KEY', { data: 42 })
+    const result = await service.getSecretJSON('JSON_KEY')
+    assert.deepStrictEqual(result, { data: 42 })
+  })
+
+  test('should get JSON secret from environment variables', async () => {
+    const vars = new LocalVariablesService({ CONFIG: '{"port":3000}' })
+    const service = new LocalSecretService(vars)
+    const result = await service.getSecretJSON('CONFIG')
+    assert.deepStrictEqual(result, { port: 3000 })
+  })
+
+  test('should throw when JSON secret not found', async () => {
+    const vars = new LocalVariablesService({})
+    const service = new LocalSecretService(vars)
+    await assert.rejects(() => service.getSecretJSON('MISSING'), {
+      message: 'Secret Not Found: MISSING',
+    })
+  })
+
+  test('should prefer local storage over env variables', async () => {
+    const vars = new LocalVariablesService({ KEY: 'env-value' })
+    const service = new LocalSecretService(vars)
+    await service.setSecretJSON('KEY', 'local-value')
+    const result = await service.getSecret('KEY')
+    assert.strictEqual(result, '"local-value"')
+  })
+
+  test('should check hasSecret in local storage', async () => {
+    const vars = new LocalVariablesService({})
+    const service = new LocalSecretService(vars)
+    await service.setSecretJSON('EXISTS', 'yes')
+    assert.strictEqual(await service.hasSecret('EXISTS'), true)
+    assert.strictEqual(await service.hasSecret('NOPE'), false)
+  })
+
+  test('should check hasSecret in environment', async () => {
+    const vars = new LocalVariablesService({ ENV_KEY: 'val' })
+    const service = new LocalSecretService(vars)
+    assert.strictEqual(await service.hasSecret('ENV_KEY'), true)
+  })
+
+  test('should delete secret from local storage', async () => {
+    const service = new LocalSecretService()
+    await service.setSecretJSON('DEL_KEY', 'value')
+    assert.strictEqual(await service.hasSecret('DEL_KEY'), true)
+    await service.deleteSecret('DEL_KEY')
+    assert.strictEqual(await service.hasSecret('DEL_KEY'), false)
+  })
+})

package/src/services/local-secrets.ts

@@ -0,0 +1,94 @@
+import { LocalVariablesService } from './local-variables.js'
+import type { SecretService } from './secret-service.js'
+import type { VariablesService } from './variables-service.js'
+
+/**
+ * Service for retrieving secrets from environment variables.
+ * Supports storing secrets locally in memory for CLI operations.
+ */
+export class LocalSecretService implements SecretService {
+  private localSecrets: Map<string, string> = new Map()
+
+  /**
+   * Creates an instance of LocalSecretService.
+   */
+  constructor(
+    private variables: VariablesService = new LocalVariablesService()
+  ) {}
+
+  /**
+   * Retrieves a secret by key.
+   * Checks local storage first, then falls back to environment variables.
+   * @param key - The key of the secret to retrieve.
+   * @returns A promise that resolves to the secret value.
+   * @throws {Error} If the secret is not found.
+   */
+  public async getSecretJSON<R>(key: string): Promise<R> {
+    // Check local storage first
+    const localValue = this.localSecrets.get(key)
+    if (localValue) {
+      return JSON.parse(localValue)
+    }
+
+    // Fall back to environment variables
+    const value = await this.variables.get(key)
+    if (value) {
+      return JSON.parse(value)
+    }
+    throw new Error(`Secret Not Found: ${key}`)
+  }
+
+  /**
+   * Retrieves a secret by key.
+   * Checks local storage first, then falls back to environment variables.
+   * @param key - The key of the secret to retrieve.
+   * @returns A promise that resolves to the secret value.
+   * @throws {Error} If the secret is not found.
+   */
+  public async getSecret(key: string): Promise<string> {
+    // Check local storage first
+    const localValue = this.localSecrets.get(key)
+    if (localValue) {
+      return localValue
+    }
+
+    // Fall back to environment variables
+    const value = await this.variables.get(key)
+    if (value) {
+      return value
+    }
+    throw new Error(`Secret Not Found: ${key}`)
+  }
+
+  /**
+   * Stores a JSON value as a secret in local storage.
+   * @param key - The key to store the secret under.
+   * @param value - The JSON value to store.
+   * @returns A promise that resolves when the secret is stored.
+   */
+  public async setSecretJSON(key: string, value: unknown): Promise<void> {
+    this.localSecrets.set(key, JSON.stringify(value))
+  }
+
+  /**
+   * Checks if a secret exists without throwing.
+   * @param key - The key of the secret to check.
+   * @returns A promise that resolves to true if the secret exists.
+   */
+  public async hasSecret(key: string): Promise<boolean> {
+    if (this.localSecrets.has(key)) {
+      return true
+    }
+    const value = await this.variables.get(key)
+    return value !== undefined && value !== null && value !== ''
+  }
+
+  /**
+   * Deletes a secret from local storage.
+   * @param key - The key of the secret to delete.
+   * @returns A promise that resolves when the secret is deleted.
+   */
+  public async deleteSecret(key: string): Promise<void> {
+    this.localSecrets.delete(key)
+  }
+}

package/src/services/local-variables.test.ts

@@ -0,0 +1,61 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert'
+import { LocalVariablesService } from './local-variables.js'
+
+describe('LocalVariablesService', () => {
+  test('should get a variable', () => {
+    const service = new LocalVariablesService({ MY_VAR: 'hello' })
+    assert.strictEqual(service.get('MY_VAR'), 'hello')
+  })
+
+  test('should return undefined for missing variable', () => {
+    const service = new LocalVariablesService({})
+    assert.strictEqual(service.get('MISSING'), undefined)
+  })
+
+  test('should set a variable', () => {
+    const service = new LocalVariablesService({})
+    service.set('KEY', 'value')
+    assert.strictEqual(service.get('KEY'), 'value')
+  })
+
+  test('should delete a variable', () => {
+    const service = new LocalVariablesService({ KEY: 'val' })
+    service.delete('KEY')
+    assert.strictEqual(service.get('KEY'), undefined)
+  })
+
+  test('should check if variable exists', () => {
+    const service = new LocalVariablesService({ KEY: 'val' })
+    assert.strictEqual(service.has('KEY'), true)
+    assert.strictEqual(service.has('MISSING'), false)
+  })
+
+  test('should get all variables', () => {
+    const vars = { A: '1', B: '2' }
+    const service = new LocalVariablesService(vars)
+    assert.deepStrictEqual(service.getAll(), vars)
+  })
+
+  test('should get JSON variable', () => {
+    const service = new LocalVariablesService({ DATA: '{"key":"val"}' })
+    const result = service.getJSON('DATA')
+    assert.deepStrictEqual(result, { key: 'val' })
+  })
+
+  test('should return undefined for missing JSON variable', () => {
+    const service = new LocalVariablesService({})
+    assert.strictEqual(service.getJSON('MISSING'), undefined)
+  })
+
+  test('should set JSON variable', () => {
+    const service = new LocalVariablesService({})
+    service.setJSON('DATA', { key: 'val' })
+    assert.strictEqual(service.get('DATA'), '{"key":"val"}')
+  })
+
+  test('should handle has with undefined value', () => {
+    const service = new LocalVariablesService({ KEY: undefined })
+    assert.strictEqual(service.has('KEY'), false)
+  })
+})

package/src/services/local-variables.ts

@@ -0,0 +1,39 @@
+import type { VariablesService } from './variables-service.js'
+
+export class LocalVariablesService implements VariablesService {
+  constructor(
+    private variables: Record<string, string | undefined> = process.env
+  ) {}
+
+  public getAll():
+    | Promise<Record<string, string | undefined>>
+    | Record<string, string | undefined> {
+    return this.variables || {}
+  }
+
+  public get(name: string): Promise<string | undefined> | string | undefined {
+    return this.variables[name]
+  }
+
+  public getJSON<T = unknown>(name: string): T | undefined {
+    const value = this.variables[name]
+    if (value === undefined) return undefined
+    return JSON.parse(value)
+  }
+
+  public set(name: string, value: string): void {
+    this.variables[name] = value
+  }
+
+  public setJSON(name: string, value: unknown): void {
+    this.variables[name] = JSON.stringify(value)
+  }
+
+  public has(name: string): boolean {
+    return name in this.variables && this.variables[name] !== undefined
+  }
+
+  public delete(name: string): void {
+    delete this.variables[name]
+  }
+}

package/src/services/logger-console.test.ts

@@ -0,0 +1,118 @@
+import { describe, test, beforeEach } from 'node:test'
+import assert from 'node:assert'
+import { ConsoleLogger } from './logger-console.js'
+import { LogLevel } from './logger.js'
+
+describe('ConsoleLogger', () => {
+  let logger: ConsoleLogger
+  let captured: { method: string; args: any[] }[]
+  let origConsole: Record<string, any>
+
+  beforeEach(() => {
+    logger = new ConsoleLogger()
+    captured = []
+    origConsole = {
+      trace: console.trace,
+      debug: console.debug,
+      info: console.info,
+      warn: console.warn,
+      error: console.error,
+      log: console.log,
+    }
+    console.trace = (...args: any[]) => captured.push({ method: 'trace', args })
+    console.debug = (...args: any[]) => captured.push({ method: 'debug', args })
+    console.info = (...args: any[]) => captured.push({ method: 'info', args })
+    console.warn = (...args: any[]) => captured.push({ method: 'warn', args })
+    console.error = (...args: any[]) => captured.push({ method: 'error', args })
+    console.log = (...args: any[]) => captured.push({ method: 'log', args })
+  })
+
+  // Restore console after each test
+  test('should log info at default level', () => {
+    logger.info('test message')
+    assert.strictEqual(captured.length, 1)
+    assert.strictEqual(captured[0].method, 'info')
+    assert.ok(captured[0].args.includes('test message'))
+    Object.assign(console, origConsole)
+  })
+
+  test('should not log debug at default info level', () => {
+    logger.debug('debug message')
+    assert.strictEqual(captured.length, 0)
+    Object.assign(console, origConsole)
+  })
+
+  test('should log debug when level is set to debug', () => {
+    logger.setLevel(LogLevel.debug)
+    logger.debug('debug message')
+    assert.strictEqual(captured.length, 1)
+    assert.strictEqual(captured[0].method, 'debug')
+    Object.assign(console, origConsole)
+  })
+
+  test('should log warn at info level', () => {
+    logger.warn('warning')
+    assert.strictEqual(captured.length, 1)
+    assert.strictEqual(captured[0].method, 'warn')
+    Object.assign(console, origConsole)
+  })
+
+  test('should log error at info level', () => {
+    logger.error('error message')
+    assert.strictEqual(captured.length, 1)
+    assert.strictEqual(captured[0].method, 'error')
+    Object.assign(console, origConsole)
+  })
+
+  test('should log Error instance with stack trace', () => {
+    const err = new Error('test error')
+    logger.error(err)
+    assert.strictEqual(captured.length, 2) // error message + stack
+    assert.ok(captured[0].args.includes('test error'))
+    assert.strictEqual(captured[1].args[0], 'STACK:')
+    Object.assign(console, origConsole)
+  })
+
+  test('should not log info when level is error', () => {
+    logger.setLevel(LogLevel.error)
+    logger.info('info')
+    logger.warn('warn')
+    logger.debug('debug')
+    assert.strictEqual(captured.length, 0)
+    Object.assign(console, origConsole)
+  })
+
+  test('should log error when level is error', () => {
+    logger.setLevel(LogLevel.error)
+    logger.error('critical')
+    assert.strictEqual(captured.length, 1)
+    Object.assign(console, origConsole)
+  })
+
+  test('should support trace level when enabled', () => {
+    logger.setLevel(LogLevel.trace)
+    logger.trace!('trace message')
+    assert.strictEqual(captured.length, 1)
+    assert.strictEqual(captured[0].method, 'trace')
+    Object.assign(console, origConsole)
+  })
+
+  test('should log with additional metadata', () => {
+    logger.info('message', { extra: 'data' })
+    assert.ok(captured[0].args.includes('message'))
+    Object.assign(console, origConsole)
+  })
+
+  test('should handle object messages in info', () => {
+    logger.info({ key: 'value' })
+    assert.strictEqual(captured.length, 1)
+    Object.assign(console, origConsole)
+  })
+
+  test('log method should respect level', () => {
+    logger.setLevel(LogLevel.error)
+    logger.log('info', 'should not show')
+    assert.strictEqual(captured.length, 0)
+    Object.assign(console, origConsole)
+  })
+})

package/src/services/logger-console.ts

@@ -0,0 +1,98 @@
+import type { Logger } from './logger.js'
+import { LogLevel } from './logger.js'
+
+/**
+ * A logger implementation that logs messages to the console.
+ */
+export class ConsoleLogger implements Logger {
+  /**
+   * The current logging level.
+   */
+  private level: LogLevel = LogLevel.info
+
+  /**
+   * Sets the logging level.
+   * @param level - The logging level to set.
+   */
+  setLevel(level: LogLevel): void {
+    this.level = level
+  }
+
+  /**
+   * Logs a trace message.
+   * @param message - The message to log.
+   * @param meta - Additional metadata to log.
+   */
+  trace?(message: string, ...meta: any[]): void {
+    if (this.level <= LogLevel.trace) {
+      console.trace('TRACE:', message, ...meta)
+    }
+  }
+
+  /**
+   * Logs a debug message.
+   * @param message - The message to log.
+   * @param meta - Additional metadata to log.
+   */
+  debug(message: string, ...meta: any[]): void {
+    if (this.level <= LogLevel.debug) {
+      console.debug('DEBUG:', message, ...meta)
+    }
+  }
+
+  /**
+   * Logs an informational message.
+   * @param messageOrObj - The message or object to log.
+   * @param meta - Additional metadata to log.
+   */
+  info(messageOrObj: string | Record<string, any>, ...meta: any[]): void {
+    if (this.level <= LogLevel.info) {
+      console.info('INFO:', messageOrObj, ...meta)
+    }
+  }
+
+  /**
+   * Logs a warning message.
+   * @param messageOrObj - The message or object to log.
+   * @param meta - Additional metadata to log.
+   */
+  warn(messageOrObj: string | Record<string, any>, ...meta: any[]): void {
+    if (this.level <= LogLevel.warn) {
+      console.warn('WARN:', messageOrObj, ...meta)
+    }
+  }
+
+  /**
+   * Logs an error message.
+   * @param messageOrObj - The message, object, or error to log.
+   * @param meta - Additional metadata to log.
+   */
+  error(
+    messageOrObj: string | Record<string, any> | Error,
+    ...meta: any[]
+  ): void {
+    if (this.level <= LogLevel.error) {
+      console.error(
+        'ERROR:',
+        messageOrObj instanceof Error ? messageOrObj.message : messageOrObj,
+        ...meta
+      )
+      if (messageOrObj instanceof Error) {
+        console.error('STACK:', messageOrObj.stack)
+      }
+    }
+  }
+
+  /**
+   * Logs a message at a specified level.
+   * @param level - The logging level.
+   * @param message - The message to log.
+   * @param meta - Additional metadata to log.
+   */
+  log(level: string, message: string, ...meta: any[]): void {
+    const logLevel = LogLevel[level as keyof typeof LogLevel]
+    if (this.level <= logLevel) {
+      console.log(`${level.toUpperCase()}:`, message, ...meta)
+    }
+  }
+}

package/src/services/logger.ts

@@ -0,0 +1,57 @@
+export enum LogLevel {
+  'trace', // Add this level
+  'debug',
+  'info',
+  'warn',
+  'error',
+  'critical',
+}
+
+/**
+ * Interface for logging messages at various levels.
+ */
+export interface Logger {
+  /**
+   * Logs an informational message.
+   * @param messageOrObj - The message or object to log.
+   * @param meta - Additional metadata to log.
+   */
+  info(messageOrObj: string | Record<string, any>, ...meta: any[]): void
+
+  /**
+   * Logs a warning message.
+   * @param messageOrObj - The message or object to log.
+   * @param meta - Additional metadata to log.
+   */
+  warn(messageOrObj: string | Record<string, any>, ...meta: any[]): void
+
+  /**
+   * Logs an error message.
+   * @param messageOrObj - The message, object, or error to log.
+   * @param meta - Additional metadata to log.
+   */
+  error(
+    messageOrObj: string | Record<string, any> | Error,
+    ...meta: any[]
+  ): void
+
+  /**
+   * Logs a debug message.
+   * @param message - The message to log.
+   * @param meta - Additional metadata to log.
+   */
+  debug(message: string, ...meta: any[]): void
+
+  /**
+   * Logs a trace message.
+   * @param message - The message to log.
+   * @param meta - Additional metadata to log.
+   */
+  trace?(message: string, ...meta: any[]): void
+
+  /**
+   * Sets the logging level.
+   * @param level - The logging level to set.
+   */
+  setLevel(level: LogLevel): void
+}

package/src/services/scheduler-service.ts

@@ -0,0 +1,86 @@
+import type { CoreUserSession } from '../types/core.types.js'
+
+/**
+ * Minimal metadata for listing scheduled tasks
+ */
+export interface ScheduledTaskSummary {
+  /** Unique task ID */
+  taskId: string
+  /** RPC function name to invoke */
+  rpcName: string
+  /** Scheduled execution time */
+  scheduledFor: Date
+}
+
+/**
+ * Full metadata for a scheduled task retrieved from the queue
+ */
+export interface ScheduledTaskInfo extends ScheduledTaskSummary {
+  /** Data to pass to the RPC function */
+  data?: any
+  /** User session */
+  session?: CoreUserSession
+  /** Task status */
+  status?: 'scheduled' | 'active' | 'completed' | 'failed'
+}
+
+/**
+ * Abstract scheduler service for persistent scheduled task management
+ * Implementations use queue backends (pg-boss, BullMQ) for distributed scheduling
+ */
+export abstract class SchedulerService {
+  /**
+   * Initialize the scheduler service
+   */
+  abstract init(): Promise<void>
+
+  /**
+   * Schedule a one-off delayed RPC call
+   * @param delay - Delay before execution (number in milliseconds or duration string like "5h", "30m")
+   * @param rpcName - RPC function name to invoke
+   * @param data - Data to pass to the RPC function
+   * @param session - Optional user session
+   * @returns Task ID
+   */
+  abstract scheduleRPC(
+    delay: number | string,
+    rpcName: string,
+    data?: any,
+    session?: CoreUserSession
+  ): Promise<string>
+
+  /**
+   * Unschedule a task by ID
+   * @param taskId - Task ID
+   * @returns Success status
+   */
+  abstract unschedule(taskId: string): Promise<boolean>
+
+  /**
+   * Get a scheduled task by ID with full details
+   * @param taskId - Task ID
+   * @returns Task info or null if not found
+   */
+  abstract getTask(taskId: string): Promise<ScheduledTaskInfo | null>
+
+  /**
+   * Get all scheduled tasks with minimal info
+   * @returns Array of task summaries with taskId, rpcName, and schedule
+   */
+  abstract getAllTasks(): Promise<ScheduledTaskSummary[]>
+
+  /**
+   * Close any open connections
+   */
+  abstract close(): Promise<void>
+
+  /**
+   * Start recurring scheduled tasks
+   */
+  async start(): Promise<void> {}
+
+  /**
+   * Stop recurring scheduled tasks
+   */
+  async stop(): Promise<void> {}
+}