@pikku/core 0.12.107 → 0.12.111

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

@@ -1,204 +0,0 @@
-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 <T = string>(key: string): Promise<T> => {
-    const val = store.get(key)
-    if (!val) throw new Error(`Not found: ${key}`)
-    try {
-      return JSON.parse(val) as T
-    } catch {
-      return val as unknown as T
-    }
-  },
-  hasSecret: async (key: string) => store.has(key),
-  setSecret: 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 getSecret with type to underlying service', async () => {
-    const store = new Map([['CONFIG', '{"port":3000}']])
-    const service = new TypedSecretService(createMockSecrets(store), {})
-    const result = await service.getSecret<{ port: number }>('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 setSecret to underlying service', async () => {
-    const store = new Map<string, string>()
-    const service = new TypedSecretService(createMockSecrets(store), {})
-    await service.setSecret('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 cache getSecret and not re-hit the underlying service', async () => {
-    let calls = 0
-    const inner = {
-      getSecret: async <T = string>(key: string): Promise<T> => {
-        calls++
-        return `v-${key}` as unknown as T
-      },
-      hasSecret: async () => true,
-      setSecret: async () => {},
-      deleteSecret: async () => {},
-    }
-    const service = new TypedSecretService(inner, {})
-    assert.strictEqual(await service.getSecret('K'), 'v-K')
-    assert.strictEqual(await service.getSecret('K'), 'v-K')
-    assert.strictEqual(calls, 1)
-  })
-
-  test('should invalidate the cache on setSecret and deleteSecret', async () => {
-    const store = new Map([['K', '"a"']])
-    const service = new TypedSecretService(createMockSecrets(store), {})
-    assert.strictEqual(await service.getSecret('K'), 'a')
-    await service.setSecret('K', 'b')
-    assert.strictEqual(await service.getSecret('K'), 'b')
-    await service.deleteSecret('K')
-    await assert.rejects(() => service.getSecret('K'))
-  })
-
-  test('should not cache a getSecret miss', async () => {
-    const store = new Map<string, string>()
-    const service = new TypedSecretService(createMockSecrets(store), {})
-    await assert.rejects(() => service.getSecret('K'))
-    store.set('K', '"now-here"')
-    assert.strictEqual(await service.getSecret('K'), 'now-here')
-  })
-
-  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')
-  })
-
-  test('an optional secret that is missing resolves undefined instead of throwing', async () => {
-    // getSecret throws for a missing secret, which is right for a required one:
-    // the app cannot run without it. An optional secret's absence is a supported
-    // state, so throwing forces every caller into a `.catch(() => null)` that
-    // also swallows a real vault failure.
-    const service = new TypedSecretService(createMockSecrets(), {
-      SCENARIO_ACTOR_SECRET: {
-        name: 'scenarioActor',
-        displayName: 'Scenario Actor Secret',
-        optional: true,
-      },
-    })
-    assert.strictEqual(
-      await service.getSecret('SCENARIO_ACTOR_SECRET'),
-      undefined
-    )
-  })
-
-  test('an optional secret that IS set resolves its value', async () => {
-    const store = new Map([['SCENARIO_ACTOR_SECRET', '"shh"']])
-    const service = new TypedSecretService(createMockSecrets(store), {
-      SCENARIO_ACTOR_SECRET: {
-        name: 'scenarioActor',
-        displayName: 'Scenario Actor Secret',
-        optional: true,
-      },
-    })
-    assert.strictEqual(await service.getSecret('SCENARIO_ACTOR_SECRET'), 'shh')
-  })
-
-  test('a missing secret still throws unless it declared itself optional', async () => {
-    const service = new TypedSecretService(createMockSecrets(), {
-      STRIPE_KEY: { name: 'stripe', displayName: 'Stripe' },
-    })
-    await assert.rejects(() => service.getSecret('STRIPE_KEY'))
-  })
-
-  test('a resolved-absent optional secret still reports hasSecret false', async () => {
-    // The cache stores `undefined` to remember the absence, so a `has(key)`
-    // test on it answers "we have looked", not "there is a value". Reading an
-    // optional secret must not turn its own absence into a claim it is set.
-    const service = new TypedSecretService(createMockSecrets(), {
-      OPTIONAL: { name: 'opt', displayName: 'Optional', optional: true },
-    })
-    assert.strictEqual(await service.getSecret('OPTIONAL'), undefined)
-    assert.strictEqual(await service.hasSecret('OPTIONAL'), false)
-  })
-
-  test('an optional secret set after an absent read is picked up', async () => {
-    const store = new Map<string, string>()
-    const service = new TypedSecretService(createMockSecrets(store), {
-      OPTIONAL: { name: 'opt', displayName: 'Optional', optional: true },
-    })
-    assert.strictEqual(await service.getSecret('OPTIONAL'), undefined)
-    await service.setSecret('OPTIONAL', 'later')
-    assert.strictEqual(await service.hasSecret('OPTIONAL'), true)
-    assert.strictEqual(await service.getSecret('OPTIONAL'), 'later')
-  })
-
-  test('an optional secret does not re-hit the store once resolved', async () => {
-    let reads = 0
-    const base = createMockSecrets()
-    const service = new TypedSecretService(
-      {
-        ...base,
-        hasSecret: async (key: string) => {
-          reads++
-          return base.hasSecret(key)
-        },
-      },
-      { OPTIONAL: { name: 'opt', displayName: 'Optional', optional: true } }
-    )
-    await service.getSecret('OPTIONAL')
-    await service.getSecret('OPTIONAL')
-    assert.strictEqual(reads, 1)
-  })
-})

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

@@ -1,132 +0,0 @@
-import type { SecretValue } from '../classification/secret-value.js'
-import type { SecretService, SecretValues } from './secret-service.js'
-
-/**
- * The wrapper, or `undefined` when the generated map declares the key as an
- * optional property. The `undefined` has to be lifted OUT of `SecretValue` —
- * a missing optional secret resolves to `undefined` itself, not to a wrapper
- * around it, so `SecretValue<T | undefined>` would type a value that never
- * exists and hide the `undefined` behind a `.reveal()` the caller never reaches.
- */
-export type SecretResult<T> = undefined extends T
-  ? SecretValue<Exclude<T, undefined>> | undefined
-  : SecretValue<T>
-
-export interface CredentialStatus {
-  secretId: string
-  name: string
-  displayName: string
-  isConfigured: boolean
-  oauth2?: { tokenSecretId: string }
-}
-
-export type CredentialMeta = {
-  name: string
-  displayName: string
-  /**
-   * Declared `optional: true`, so absence is a supported state rather than a
-   * misconfiguration. The generated map types the key as an optional property,
-   * which is what puts `undefined` in `getSecret`'s return type.
-   */
-  optional?: boolean
-  oauth2?: { tokenSecretId: string }
-}
-
-export class TypedSecretService<
-  TMap = Record<string, unknown>,
-> implements SecretService {
-  // knowledge: decisions/internals/typed-secret-service-caches-for-the-process-lifetime.md
-  private cache = new Map<string, unknown>()
-
-  constructor(
-    private secrets: SecretService,
-    private credentialsMeta: Record<string, CredentialMeta>
-  ) {}
-
-  async getSecret<K extends keyof TMap & string>(
-    key: K
-  ): Promise<SecretResult<TMap[K]>>
-  async getSecret<T = string>(key: string): Promise<SecretValue<T>>
-  async getSecret(key: string): Promise<unknown> {
-    if (this.cache.has(key)) {
-      return this.cache.get(key)
-    }
-    if (
-      this.credentialsMeta[key]?.optional &&
-      !(await this.secrets.hasSecret(key))
-    ) {
-      this.cache.set(key, undefined)
-      return undefined
-    }
-    const value = await this.secrets.getSecret(key)
-    this.cache.set(key, value)
-    return value
-  }
-
-  async hasSecret(key: string): Promise<boolean> {
-    // `undefined` is cached for an optional secret that resolved absent, so a
-    // cache hit means "already looked", not "there is a value". Reporting true
-    // for it would let a read of an optional secret assert its own presence.
-    if (this.cache.has(key)) {
-      return this.cache.get(key) !== undefined
-    }
-    return this.secrets.hasSecret(key)
-  }
-
-  async setSecret<K extends string>(
-    key: K,
-    value: K extends keyof TMap ? TMap[K] : unknown
-  ): Promise<void> {
-    await this.secrets.setSecret(key, value)
-    this.cache.delete(key)
-  }
-
-  async deleteSecret(key: string): Promise<void> {
-    await this.secrets.deleteSecret(key)
-    this.cache.delete(key)
-  }
-
-  async getSecrets<T extends Record<string, unknown> = Record<string, unknown>>(
-    keys: (keyof T & string)[]
-  ): Promise<Partial<SecretValues<T>>> {
-    const result: Partial<SecretValues<T>> = {}
-    const missing: (keyof T & string)[] = []
-    for (const key of keys) {
-      if (this.cache.has(key)) {
-        result[key] = this.cache.get(key) as SecretValues<T>[keyof T & string]
-      } else {
-        missing.push(key)
-      }
-    }
-    if (missing.length > 0) {
-      const fetched = await this.secrets.getSecrets<T>(missing)
-      for (const [key, value] of Object.entries(fetched)) {
-        this.cache.set(key, value)
-        result[key as keyof T & string] = value as SecretValues<T>[keyof T &
-          string]
-      }
-    }
-    return result
-  }
-
-  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

@@ -1,166 +0,0 @@
-import { describe, test } from 'node:test'
-import assert from 'node:assert'
-import { TypedVariablesService } from './typed-variables-service.js'
-import { LocalVariablesService } from './local-variables.js'
-import type { StandardSchemaV1 } from '@standard-schema/spec'
-
-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 get to underlying service', () => {
-    const service = createService({ DATA: '{"key":"val"}' })
-    assert.deepStrictEqual(service.get('DATA'), { key: 'val' })
-  })
-
-  test('should delegate set to underlying service', () => {
-    const service = createService()
-    service.set('DATA', { key: 'val' })
-    assert.deepStrictEqual(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)
-  })
-})
-
-/**
- * Stands in for `z.enum([...]).default(...)`: a schema that answers `undefined`
- * with a value rather than an issue. Core declares no schema library of its
- * own, so the contract under test is Standard Schema's, not Zod's.
- */
-const withDefault = <T>(value: T): StandardSchemaV1<unknown, T> => ({
-  '~standard': {
-    version: 1,
-    vendor: 'test',
-    validate: (input: unknown) =>
-      input === undefined ? { value } : { value: input as T },
-  },
-})
-
-const noDefault: StandardSchemaV1<unknown, string> = {
-  '~standard': {
-    version: 1,
-    vendor: 'test',
-    validate: (input: unknown) =>
-      typeof input === 'string'
-        ? { value: input }
-        : { issues: [{ message: 'expected a string' }] },
-  },
-}
-
-describe('TypedVariablesService schema defaults', () => {
-  const createService = (vars: Record<string, string | undefined> = {}) =>
-    new TypedVariablesService(new LocalVariablesService(vars), {
-      GITHUB_BASE_URL: {
-        name: 'GITHUB_BASE_URL',
-        displayName: 'GitHub Base URL',
-        schema: withDefault('https://api.github.com'),
-      },
-      API_KEY: {
-        name: 'API_KEY',
-        displayName: 'API Key',
-        schema: noDefault,
-      },
-      // The form code generation emits, deferred past the import cycle.
-      REGION: {
-        name: 'REGION',
-        displayName: 'Region',
-        schema: () => withDefault('eu-west-1'),
-      },
-    })
-
-  test('resolves a declared default when the host sets nothing', async () => {
-    const service = createService()
-    assert.strictEqual(
-      await service.get('GITHUB_BASE_URL'),
-      'https://api.github.com'
-    )
-  })
-
-  test('prefers the host value over the default', async () => {
-    const service = createService({ GITHUB_BASE_URL: 'https://ghe.internal' })
-    assert.strictEqual(
-      await service.get('GITHUB_BASE_URL'),
-      'https://ghe.internal'
-    )
-  })
-
-  test('stays undefined when the schema carries no default', async () => {
-    const service = createService()
-    assert.strictEqual(await service.get('API_KEY'), undefined)
-  })
-
-  test('resolves a default behind a thunk', async () => {
-    const service = createService()
-    assert.strictEqual(await service.get('REGION'), 'eu-west-1')
-  })
-
-  test('a defaulted variable is not missing', async () => {
-    const service = createService()
-    const missing = await service.getMissing()
-    assert.deepStrictEqual(
-      missing.map((v) => v.variableId),
-      ['API_KEY']
-    )
-  })
-
-  test('status separates having a default from being configured', async () => {
-    const service = createService()
-    const status = await service.getAllStatus()
-    const github = status.find((s) => s.variableId === 'GITHUB_BASE_URL')!
-    assert.strictEqual(github.isConfigured, false)
-    assert.strictEqual(github.hasDefault, true)
-    const apiKey = status.find((s) => s.variableId === 'API_KEY')!
-    assert.strictEqual(apiKey.hasDefault, false)
-  })
-})

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

@@ -1,166 +0,0 @@
-import type { StandardSchemaV1 } from '@standard-schema/spec'
-import type { VariablesService } from './variables-service.js'
-
-export interface VariableStatus {
-  variableId: string
-  name: string
-  displayName: string
-  isConfigured: boolean
-  /** Whether the declaration answers for itself when the host sets nothing. */
-  hasDefault: boolean
-}
-
-export type VariableMeta = {
-  name: string
-  displayName: string
-  /**
-   * The shape the variable was declared with. It is the schema itself rather
-   * than a description of it, because a default is only knowable by running it:
-   * `undefined` goes in and, if the declaration carries one, the default comes
-   * back out.
-   *
-   * A thunk is accepted, and is what code generation emits. The generated file
-   * and the file declaring the schema import each other, so reading the schema
-   * while the modules are still initializing throws — deferring the read until
-   * a variable is actually asked for is what keeps the cycle harmless.
-   */
-  schema?: StandardSchemaV1 | (() => StandardSchemaV1)
-}
-
-const isPromise = (value: unknown): value is Promise<unknown> =>
-  typeof (value as Promise<unknown> | undefined)?.then === 'function'
-
-/**
- * A declared default is the answer to a variable nobody set, so it is resolved
- * here rather than in `VariablesService`: the store knows what a host has put
- * in it, and only this layer knows what was declared.
- */
-export class TypedVariablesService<
-  TMap = Record<string, unknown>,
-> implements VariablesService {
-  constructor(
-    private variables: VariablesService,
-    private variablesMeta: Record<string, VariableMeta>
-  ) {}
-
-  get<K extends keyof TMap & string>(
-    name: K
-  ): Promise<TMap[K] | undefined> | TMap[K] | undefined
-  get<T = string>(name: string): Promise<T | undefined> | T | undefined
-  get(name: string): Promise<unknown> | unknown {
-    const stored = this.variables.get(name)
-    if (isPromise(stored)) {
-      return stored.then((value) =>
-        value === undefined ? this.resolveDefault(name) : value
-      )
-    }
-    return stored === undefined ? this.resolveDefault(name) : stored
-  }
-
-  getVariables<T extends Record<string, unknown> = Record<string, unknown>>(
-    names: (keyof T & string)[]
-  ): Promise<Partial<T>> | Partial<T> {
-    const stored = this.variables.getVariables<T>(names)
-    if (isPromise(stored)) {
-      return stored.then((values) => this.withDefaults(names, values))
-    }
-    return this.withDefaults(names, stored)
-  }
-
-  getAll():
-    | Promise<Record<string, string | undefined>>
-    | Record<string, string | undefined> {
-    return this.variables.getAll()
-  }
-
-  set(name: string, value: unknown): Promise<void> | void {
-    return this.variables.set(name, value)
-  }
-
-  has(name: string): Promise<boolean> | boolean {
-    return this.variables.has(name)
-  }
-
-  delete(name: string): Promise<void> | void {
-    return this.variables.delete(name)
-  }
-
-  async getAllStatus(): Promise<VariableStatus[]> {
-    const results: VariableStatus[] = []
-    const all = await this.variables.getAll()
-
-    for (const [variableId, meta] of Object.entries(this.variablesMeta)) {
-      results.push({
-        variableId,
-        name: meta.name,
-        displayName: meta.displayName,
-        isConfigured: all[variableId] !== undefined,
-        hasDefault: (await this.resolveDefault(variableId)) !== undefined,
-      })
-    }
-
-    return results
-  }
-
-  /**
-   * What a deployment still has to be told. A variable that defaults is not on
-   * this list — it has a value, just not one anybody has to supply.
-   */
-  async getMissing(): Promise<VariableStatus[]> {
-    const all = await this.getAllStatus()
-    return all.filter((v) => !v.isConfigured && !v.hasDefault)
-  }
-
-  /**
-   * The value the declaration answers with when the host set nothing, or
-   * `undefined` when it does not answer for itself.
-   */
-  private resolveDefault(name: string): Promise<unknown> | unknown {
-    const declared = this.variablesMeta[name]?.schema
-    if (!declared) {
-      return undefined
-    }
-    const schema = typeof declared === 'function' ? declared() : declared
-    const result = schema['~standard'].validate(undefined)
-    if (isPromise(result)) {
-      return result.then(unwrapDefault)
-    }
-    return unwrapDefault(result)
-  }
-
-  /**
-   * Kept synchronous when the defaults resolve synchronously, so a caller that
-   * did not await `getVariables` before does not have to start.
-   */
-  private withDefaults<T extends Record<string, unknown>>(
-    names: (keyof T & string)[],
-    values: Partial<T>
-  ): Promise<Partial<T>> | Partial<T> {
-    const out: Record<string, unknown> = { ...values }
-    const pending: Promise<void>[] = []
-    for (const name of names) {
-      if (out[name] !== undefined) continue
-      const fallback = this.resolveDefault(name)
-      if (isPromise(fallback)) {
-        pending.push(
-          fallback.then((value) => {
-            if (value !== undefined) out[name] = value
-          })
-        )
-      } else if (fallback !== undefined) {
-        out[name] = fallback
-      }
-    }
-    if (pending.length > 0) {
-      return Promise.all(pending).then(() => out as Partial<T>)
-    }
-    return out as Partial<T>
-  }
-}
-
-/**
- * A schema with no default rejects `undefined`, which is not a failure here —
- * it is the answer that there is nothing to fall back to.
- */
-const unwrapDefault = (result: StandardSchemaV1.Result<unknown>) =>
-  result.issues ? undefined : result.value