@pikku/core 0.11.2 → 0.12.1

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

@@ -1,4 +1,4 @@
-import { VariablesService } from './variables-service.js'
+import type { VariablesService } from './variables-service.js'
 
 export class LocalVariablesService implements VariablesService {
   constructor(
@@ -14,4 +14,26 @@ export class LocalVariablesService implements VariablesService {
   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

@@ -1,4 +1,5 @@
-import { Logger, LogLevel } from './logger.js'
+import type { Logger } from './logger.js'
+import { LogLevel } from './logger.js'
 
 /**
  * A logger implementation that logs messages to the console.

package/src/services/scheduler-service.ts

@@ -1,4 +1,4 @@
-import { CoreUserSession } from '../types/core.types.js'
+import type { CoreUserSession } from '../types/core.types.js'
 
 /**
  * Minimal metadata for listing scheduled tasks
@@ -73,4 +73,14 @@ export abstract class SchedulerService {
    * Close any open connections
    */
   abstract close(): Promise<void>
+
+  /**
+   * Start recurring scheduled tasks
+   */
+  async start(): Promise<void> {}
+
+  /**
+   * Stop recurring scheduled tasks
+   */
+  async stop(): Promise<void> {}
 }

package/src/services/schema-service.ts

@@ -23,4 +23,11 @@ export interface SchemaService {
    * @returns {Set<string>} A set containing the names of all available schemas.
    */
   getSchemaNames: () => Set<string>
+
+  /**
+   * Retrieves the property keys from a compiled JSON schema.
+   * @param {string} schemaName - The name of the schema.
+   * @returns {string[]} An array of property keys, or empty array if schema not found.
+   */
+  getSchemaKeys: (schemaName: string) => string[]
 }

package/src/services/scoped-secret-service.test.ts

@@ -0,0 +1,74 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert'
+import { ScopedSecretService } from './scoped-secret-service.js'
+
+const createMockSecrets = () => ({
+  getSecret: async (key: string) => `value-of-${key}`,
+  getSecretJSON: async (key: string) => ({ key }),
+  hasSecret: async () => true,
+  setSecretJSON: async () => {},
+  deleteSecret: async () => {},
+})
+
+describe('ScopedSecretService', () => {
+  test('should allow access to allowed keys', async () => {
+    const mock = createMockSecrets()
+    const scoped = new ScopedSecretService(mock, new Set(['KEY1', 'KEY2']))
+    const result = await scoped.getSecret('KEY1')
+    assert.strictEqual(result, 'value-of-KEY1')
+  })
+
+  test('should deny access to non-allowed keys', async () => {
+    const mock = createMockSecrets()
+    const scoped = new ScopedSecretService(mock, new Set(['KEY1']))
+    await assert.rejects(() => scoped.getSecret('KEY2'), {
+      message: 'Access denied to secret key: KEY2',
+    })
+  })
+
+  test('should allow getSecretJSON for allowed keys', async () => {
+    const mock = createMockSecrets()
+    const scoped = new ScopedSecretService(mock, new Set(['KEY1']))
+    const result = await scoped.getSecretJSON('KEY1')
+    assert.deepStrictEqual(result, { key: 'KEY1' })
+  })
+
+  test('should deny getSecretJSON for non-allowed keys', async () => {
+    const mock = createMockSecrets()
+    const scoped = new ScopedSecretService(mock, new Set(['KEY1']))
+    await assert.rejects(() => scoped.getSecretJSON('FORBIDDEN'), {
+      message: 'Access denied to secret key: FORBIDDEN',
+    })
+  })
+
+  test('should allow hasSecret for allowed keys', async () => {
+    const mock = createMockSecrets()
+    const scoped = new ScopedSecretService(mock, new Set(['KEY1']))
+    const result = await scoped.hasSecret('KEY1')
+    assert.strictEqual(result, true)
+  })
+
+  test('should deny hasSecret for non-allowed keys', async () => {
+    const mock = createMockSecrets()
+    const scoped = new ScopedSecretService(mock, new Set(['KEY1']))
+    await assert.rejects(() => scoped.hasSecret('KEY2'), {
+      message: 'Access denied to secret key: KEY2',
+    })
+  })
+
+  test('should always throw on setSecretJSON', async () => {
+    const mock = createMockSecrets()
+    const scoped = new ScopedSecretService(mock, new Set(['KEY1']))
+    await assert.rejects(() => scoped.setSecretJSON('KEY1', 'val'), {
+      message: 'setSecretJSON is not allowed in scoped secret service',
+    })
+  })
+
+  test('should always throw on deleteSecret', async () => {
+    const mock = createMockSecrets()
+    const scoped = new ScopedSecretService(mock, new Set(['KEY1']))
+    await assert.rejects(() => scoped.deleteSecret('KEY1'), {
+      message: 'deleteSecret is not allowed in scoped secret service',
+    })
+  })
+})

package/src/services/scoped-secret-service.ts

@@ -0,0 +1,41 @@
+import type { SecretService } from './secret-service.js'
+
+/**
+ * A read-only wrapper around SecretService that restricts access
+ * to only a defined set of allowed secret keys.
+ */
+export class ScopedSecretService implements SecretService {
+  constructor(
+    private secrets: SecretService,
+    private allowedKeys: Set<string>
+  ) {}
+
+  private assertAllowed(key: string): void {
+    if (!this.allowedKeys.has(key)) {
+      throw new Error(`Access denied to secret key: ${key}`)
+    }
+  }
+
+  async getSecret(key: string): Promise<string> {
+    this.assertAllowed(key)
+    return this.secrets.getSecret(key)
+  }
+
+  async getSecretJSON<T = {}>(key: string): Promise<T> {
+    this.assertAllowed(key)
+    return this.secrets.getSecretJSON<T>(key)
+  }
+
+  async hasSecret(key: string): Promise<boolean> {
+    this.assertAllowed(key)
+    return this.secrets.hasSecret(key)
+  }
+
+  async setSecretJSON(_key: string, _value: unknown): Promise<void> {
+    throw new Error('setSecretJSON is not allowed in scoped secret service')
+  }
+
+  async deleteSecret(_key: string): Promise<void> {
+    throw new Error('deleteSecret is not allowed in scoped secret service')
+  }
+}

package/src/services/secret-service.ts

@@ -1,17 +1,38 @@
 /**
- * Interface for retrieving secrets.
+ * Interface for retrieving and managing secrets.
  */
 export interface SecretService {
   /**
-   * Retrieves a secret by key.
+   * Retrieves a secret by key and parses it as JSON.
    * @param key - The key of the secret to retrieve.
-   * @returns A promise that resolves to the secret value.
+   * @returns A promise that resolves to the parsed secret value.
+   * @throws If the secret is not found.
    */
   getSecretJSON<Return = {}>(key: string): Promise<Return>
   /**
-   * Retrieves a secret by key.
+   * Retrieves a secret by key as a string.
    * @param key - The key of the secret to retrieve.
    * @returns A promise that resolves to the secret value.
+   * @throws If the secret is not found.
    */
   getSecret(key: string): Promise<string>
+  /**
+   * 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, false otherwise.
+   */
+  hasSecret(key: string): Promise<boolean>
+  /**
+   * Stores a JSON value as a secret.
+   * @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.
+   */
+  setSecretJSON(key: string, value: unknown): Promise<void>
+  /**
+   * Deletes a secret by key.
+   * @param key - The key of the secret to delete.
+   * @returns A promise that resolves when the secret is deleted.
+   */
+  deleteSecret(key: string): Promise<void>
 }

package/src/services/trigger-service.ts

@@ -0,0 +1,17 @@
+/**
+ * Abstract TriggerService interface.
+ *
+ * Implementations manage trigger subscriptions — listening to external events
+ * and dispatching to RPC targets or workflow starts.
+ */
+export interface TriggerService {
+  /**
+   * Start all triggers
+   */
+  start(): Promise<void>
+
+  /**
+   * Stop all triggers
+   */
+  stop(): Promise<void>
+}

package/src/services/typed-secret-service.test.ts

@@ -0,0 +1,93 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert'
+import { TypedSecretService } from './typed-secret-service.js'
+
+const createMockSecrets = (store: Map<string, string> = new Map()) => ({
+  getSecret: async (key: string) => {
+    const val = store.get(key)
+    if (!val) throw new Error(`Not found: ${key}`)
+    return val
+  },
+  getSecretJSON: async (key: string) => {
+    const val = store.get(key)
+    if (!val) throw new Error(`Not found: ${key}`)
+    return JSON.parse(val)
+  },
+  hasSecret: async (key: string) => store.has(key),
+  setSecretJSON: async (key: string, value: unknown) => {
+    store.set(key, JSON.stringify(value))
+  },
+  deleteSecret: async (key: string) => {
+    store.delete(key)
+  },
+})
+
+describe('TypedSecretService', () => {
+  test('should delegate getSecret to underlying service', async () => {
+    const store = new Map([['API_KEY', 'sk-123']])
+    const service = new TypedSecretService(createMockSecrets(store), {})
+    const result = await service.getSecret('API_KEY')
+    assert.strictEqual(result, 'sk-123')
+  })
+
+  test('should delegate getSecretJSON to underlying service', async () => {
+    const store = new Map([['CONFIG', '{"port":3000}']])
+    const service = new TypedSecretService(createMockSecrets(store), {})
+    const result = await service.getSecretJSON('CONFIG')
+    assert.deepStrictEqual(result, { port: 3000 })
+  })
+
+  test('should delegate hasSecret to underlying service', async () => {
+    const store = new Map([['EXISTS', 'val']])
+    const service = new TypedSecretService(createMockSecrets(store), {})
+    assert.strictEqual(await service.hasSecret('EXISTS'), true)
+    assert.strictEqual(await service.hasSecret('MISSING'), false)
+  })
+
+  test('should delegate setSecretJSON to underlying service', async () => {
+    const store = new Map<string, string>()
+    const service = new TypedSecretService(createMockSecrets(store), {})
+    await service.setSecretJSON('NEW_KEY', { data: 'val' })
+    assert.strictEqual(store.get('NEW_KEY'), '{"data":"val"}')
+  })
+
+  test('should delegate deleteSecret to underlying service', async () => {
+    const store = new Map([['KEY', 'val']])
+    const service = new TypedSecretService(createMockSecrets(store), {})
+    await service.deleteSecret('KEY')
+    assert.strictEqual(store.has('KEY'), false)
+  })
+
+  test('should get all status for credentials', async () => {
+    const store = new Map([['STRIPE_KEY', 'sk-123']])
+    const meta = {
+      STRIPE_KEY: { name: 'stripe', displayName: 'Stripe' },
+      GITHUB_TOKEN: {
+        name: 'github',
+        displayName: 'GitHub',
+        oauth2: { tokenSecretId: 'GH_TOKEN' },
+      },
+    }
+    const service = new TypedSecretService(createMockSecrets(store), meta)
+    const status = await service.getAllStatus()
+    assert.strictEqual(status.length, 2)
+    const stripeStatus = status.find((s) => s.secretId === 'STRIPE_KEY')!
+    assert.strictEqual(stripeStatus.isConfigured, true)
+    assert.strictEqual(stripeStatus.displayName, 'Stripe')
+    const ghStatus = status.find((s) => s.secretId === 'GITHUB_TOKEN')!
+    assert.strictEqual(ghStatus.isConfigured, false)
+    assert.deepStrictEqual(ghStatus.oauth2, { tokenSecretId: 'GH_TOKEN' })
+  })
+
+  test('should get missing credentials', async () => {
+    const store = new Map([['STRIPE_KEY', 'sk-123']])
+    const meta = {
+      STRIPE_KEY: { name: 'stripe', displayName: 'Stripe' },
+      GITHUB_TOKEN: { name: 'github', displayName: 'GitHub' },
+    }
+    const service = new TypedSecretService(createMockSecrets(store), meta)
+    const missing = await service.getMissing()
+    assert.strictEqual(missing.length, 1)
+    assert.strictEqual(missing[0].secretId, 'GITHUB_TOKEN')
+  })
+})

package/src/services/typed-secret-service.ts

@@ -0,0 +1,70 @@
+import type { SecretService } from './secret-service.js'
+
+export interface CredentialStatus {
+  secretId: string
+  name: string
+  displayName: string
+  isConfigured: boolean
+  oauth2?: { tokenSecretId: string }
+}
+
+export type CredentialMeta = {
+  name: string
+  displayName: string
+  oauth2?: { tokenSecretId: string }
+}
+
+export class TypedSecretService<TMap = Record<string, unknown>>
+  implements SecretService
+{
+  constructor(
+    private secrets: SecretService,
+    private credentialsMeta: Record<string, CredentialMeta>
+  ) {}
+
+  async getSecretJSON<K extends keyof TMap & string>(key: K): Promise<TMap[K]>
+  async getSecretJSON<T = unknown>(key: string): Promise<T>
+  async getSecretJSON(key: string): Promise<unknown> {
+    return this.secrets.getSecretJSON(key)
+  }
+
+  async getSecret(key: string): Promise<string> {
+    return this.secrets.getSecret(key)
+  }
+
+  async hasSecret(key: string): Promise<boolean> {
+    return this.secrets.hasSecret(key)
+  }
+
+  async setSecretJSON<K extends string>(
+    key: K,
+    value: K extends keyof TMap ? TMap[K] : unknown
+  ): Promise<void> {
+    return this.secrets.setSecretJSON(key, value)
+  }
+
+  async deleteSecret(key: string): Promise<void> {
+    return this.secrets.deleteSecret(key)
+  }
+
+  async getAllStatus(): Promise<CredentialStatus[]> {
+    const results: CredentialStatus[] = []
+
+    for (const [secretId, meta] of Object.entries(this.credentialsMeta)) {
+      results.push({
+        secretId,
+        name: meta.name,
+        displayName: meta.displayName,
+        isConfigured: await this.secrets.hasSecret(secretId),
+        oauth2: meta.oauth2,
+      })
+    }
+
+    return results
+  }
+
+  async getMissing(): Promise<CredentialStatus[]> {
+    const all = await this.getAllStatus()
+    return all.filter((c) => !c.isConfigured)
+  }
+}

package/src/services/typed-variables-service.test.ts

@@ -0,0 +1,73 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert'
+import { TypedVariablesService } from './typed-variables-service.js'
+import { LocalVariablesService } from './local-variables.js'
+
+describe('TypedVariablesService', () => {
+  const createService = (vars: Record<string, string | undefined> = {}) => {
+    const underlying = new LocalVariablesService(vars)
+    const meta = {
+      DB_URL: { name: 'DB_URL', displayName: 'Database URL' },
+      API_KEY: { name: 'API_KEY', displayName: 'API Key' },
+    }
+    return new TypedVariablesService(underlying, meta)
+  }
+
+  test('should delegate get to underlying service', () => {
+    const service = createService({ DB_URL: 'postgres://...' })
+    assert.strictEqual(service.get('DB_URL'), 'postgres://...')
+  })
+
+  test('should delegate set to underlying service', () => {
+    const service = createService()
+    service.set('DB_URL', 'new-value')
+    assert.strictEqual(service.get('DB_URL'), 'new-value')
+  })
+
+  test('should delegate has to underlying service', () => {
+    const service = createService({ DB_URL: 'val' })
+    assert.strictEqual(service.has('DB_URL'), true)
+    assert.strictEqual(service.has('MISSING'), false)
+  })
+
+  test('should delegate delete to underlying service', () => {
+    const service = createService({ DB_URL: 'val' })
+    service.delete('DB_URL')
+    assert.strictEqual(service.has('DB_URL'), false)
+  })
+
+  test('should delegate getJSON to underlying service', () => {
+    const service = createService({ DATA: '{"key":"val"}' })
+    assert.deepStrictEqual(service.getJSON('DATA'), { key: 'val' })
+  })
+
+  test('should delegate setJSON to underlying service', () => {
+    const service = createService()
+    service.setJSON('DATA', { key: 'val' })
+    assert.strictEqual(service.get('DATA'), '{"key":"val"}')
+  })
+
+  test('should get all status for configured variables', async () => {
+    const service = createService({ DB_URL: 'postgres://...' })
+    const status = await service.getAllStatus()
+    assert.strictEqual(status.length, 2)
+    const dbStatus = status.find((s) => s.variableId === 'DB_URL')!
+    assert.strictEqual(dbStatus.isConfigured, true)
+    assert.strictEqual(dbStatus.displayName, 'Database URL')
+    const apiStatus = status.find((s) => s.variableId === 'API_KEY')!
+    assert.strictEqual(apiStatus.isConfigured, false)
+  })
+
+  test('should get missing variables', async () => {
+    const service = createService({ DB_URL: 'val' })
+    const missing = await service.getMissing()
+    assert.strictEqual(missing.length, 1)
+    assert.strictEqual(missing[0].variableId, 'API_KEY')
+  })
+
+  test('should return empty missing when all configured', async () => {
+    const service = createService({ DB_URL: 'val', API_KEY: 'key' })
+    const missing = await service.getMissing()
+    assert.strictEqual(missing.length, 0)
+  })
+})