@pikku/core 0.12.107 → 0.12.111

package/src/services/user-session-service.test.ts

@@ -1,147 +0,0 @@
-import { describe, test } from 'node:test'
-import assert from 'node:assert'
-import {
-  PikkuSessionService,
-  createMiddlewareSessionWireProps,
-  createFunctionSessionWireProps,
-} from './user-session-service.js'
-
-describe('PikkuSessionService', () => {
-  test('should set and get session', () => {
-    const service = new PikkuSessionService()
-    service.setInitial({ userId: 'user-1' })
-    const session = service.get()
-    assert.deepStrictEqual(session, { userId: 'user-1' })
-  })
-
-  test('should return undefined when no session set', () => {
-    const service = new PikkuSessionService()
-    assert.strictEqual(service.get(), undefined)
-  })
-
-  test('should mark sessionChanged when set is called', async () => {
-    const service = new PikkuSessionService()
-    assert.strictEqual(service.sessionChanged, false)
-    await service.set({ userId: 'user-1' })
-    assert.strictEqual(service.sessionChanged, true)
-  })
-
-  test('should clear session', async () => {
-    const service = new PikkuSessionService()
-    service.setInitial({ userId: 'user-1' })
-    await service.clear()
-    assert.strictEqual(service.get(), undefined)
-    assert.strictEqual(service.sessionChanged, true)
-  })
-
-  test('should freeze initial session', () => {
-    const service = new PikkuSessionService()
-    service.setInitial({ userId: 'user-1' })
-    const frozen = service.freezeInitial()
-    assert.deepStrictEqual(frozen, { userId: 'user-1' })
-  })
-
-  test('should only freeze initial once', async () => {
-    const service = new PikkuSessionService()
-    service.setInitial({ userId: 'user-1' })
-    service.freezeInitial()
-    await service.set({ userId: 'user-2' })
-    const frozen2 = service.freezeInitial()
-    assert.deepStrictEqual(frozen2, { userId: 'user-1' })
-  })
-
-  test('should persist to sessionStore on set when pikkuUserId is set', async () => {
-    let storedId: string | undefined
-    let storedSession: any
-    const store = {
-      get: async () => undefined,
-      set: async (id: string, session: any) => {
-        storedId = id
-        storedSession = session
-      },
-      clear: async () => {},
-    }
-    const service = new PikkuSessionService(store as any)
-    service.setPikkuUserId('user-123')
-    await service.set({ userId: 'new' })
-    assert.strictEqual(storedId, 'user-123')
-    assert.deepStrictEqual(storedSession, { userId: 'new' })
-  })
-
-  test('should not persist to sessionStore when pikkuUserId is not set', async () => {
-    let setCalled = false
-    const store = {
-      get: async () => undefined,
-      set: async () => {
-        setCalled = true
-      },
-      clear: async () => {},
-    }
-    const service = new PikkuSessionService(store as any)
-    await service.set({ userId: 'new' })
-    assert.strictEqual(setCalled, false)
-  })
-
-  test('should clear from sessionStore when pikkuUserId is set', async () => {
-    let clearedId: string | undefined
-    const store = {
-      get: async () => undefined,
-      set: async () => {},
-      clear: async (id: string) => {
-        clearedId = id
-      },
-    }
-    const service = new PikkuSessionService(store as any)
-    service.setPikkuUserId('user-123')
-    service.setInitial({ userId: 'user-123' })
-    await service.clear()
-    assert.strictEqual(clearedId, 'user-123')
-    assert.strictEqual(service.get(), undefined)
-  })
-
-  test('getPikkuUserId should return set value', () => {
-    const service = new PikkuSessionService()
-    assert.strictEqual(service.getPikkuUserId(), undefined)
-    service.setPikkuUserId('user-456')
-    assert.strictEqual(service.getPikkuUserId(), 'user-456')
-  })
-})
-
-describe('createMiddlewareSessionWireProps', () => {
-  test('should return session wire props', () => {
-    const service = new PikkuSessionService()
-    service.setInitial({ userId: 'user-1' })
-    const props = createMiddlewareSessionWireProps(service)
-    assert.ok('session' in props)
-    assert.ok('setSession' in props)
-    assert.ok('getSession' in props)
-    assert.ok('hasSessionChanged' in props)
-  })
-
-  test('setSession should call setInitial', () => {
-    const service = new PikkuSessionService()
-    const props = createMiddlewareSessionWireProps(service)
-    props.setSession({ userId: 'user-2' })
-    assert.deepStrictEqual(service.get(), { userId: 'user-2' })
-  })
-})
-
-describe('createFunctionSessionWireProps', () => {
-  test('should return function session wire props', () => {
-    const service = new PikkuSessionService()
-    service.setInitial({ userId: 'user-1' })
-    const props = createFunctionSessionWireProps(service)
-    assert.ok('session' in props)
-    assert.ok('setSession' in props)
-    assert.ok('clearSession' in props)
-    assert.ok('getSession' in props)
-    assert.ok('hasSessionChanged' in props)
-  })
-
-  test('session should be frozen initial', () => {
-    const service = new PikkuSessionService()
-    service.setInitial({ userId: 'user-1' })
-    const props = createFunctionSessionWireProps(service)
-    assert.deepStrictEqual(props.session, { userId: 'user-1' })
-  })
-})

package/src/services/user-session-service.ts

@@ -1,85 +0,0 @@
-import type { CoreUserSession } from '../types/core.types.js'
-import type { SessionStore } from './session-store.js'
-
-export interface SessionService<UserSession extends CoreUserSession> {
-  sessionChanged: boolean
-  initial: UserSession | undefined
-  setInitial(session: UserSession): void
-  freezeInitial(): UserSession | undefined
-  set(session: UserSession): Promise<void> | void
-  clear(): Promise<void> | void
-  get(): UserSession | undefined
-}
-
-export class PikkuSessionService<
-  UserSession extends CoreUserSession,
-> implements SessionService<UserSession> {
-  public sessionChanged = false
-  public initial: UserSession | undefined
-  protected session: UserSession | undefined
-  private pikkuUserId?: string
-
-  constructor(private sessionStore?: SessionStore<UserSession>) {}
-
-  public setPikkuUserId(id: string) {
-    this.pikkuUserId = id
-  }
-
-  public getPikkuUserId(): string | undefined {
-    return this.pikkuUserId
-  }
-
-  public setInitial(session: UserSession) {
-    this.session = session
-  }
-
-  public freezeInitial() {
-    if (this.initial === undefined) {
-      this.initial = this.session
-    }
-    return this.initial
-  }
-
-  public async set(session: UserSession) {
-    this.sessionChanged = true
-    this.session = session
-    if (this.sessionStore && this.pikkuUserId) {
-      await this.sessionStore.set(this.pikkuUserId, session)
-    }
-  }
-
-  public async clear() {
-    this.sessionChanged = true
-    this.session = undefined
-    if (this.sessionStore && this.pikkuUserId) {
-      await this.sessionStore.clear(this.pikkuUserId)
-    }
-  }
-
-  public get(): UserSession | undefined {
-    return this.session
-  }
-}
-
-export function createMiddlewareSessionWireProps<
-  UserSession extends CoreUserSession,
->(session: SessionService<UserSession>) {
-  return {
-    session: session.get() as UserSession | undefined,
-    setSession: (s: UserSession) => session.setInitial(s),
-    getSession: () => session.get(),
-    hasSessionChanged: () => session.sessionChanged,
-  }
-}
-
-export function createFunctionSessionWireProps<
-  UserSession extends CoreUserSession,
->(session: SessionService<UserSession>) {
-  return {
-    session: session.freezeInitial(),
-    setSession: (s: UserSession) => session.set(s),
-    clearSession: () => session.clear(),
-    getSession: () => session.get(),
-    hasSessionChanged: () => session.sessionChanged,
-  }
-}

package/src/services/v8-coverage-service.test.ts

@@ -1,69 +0,0 @@
-import { describe, test, after } from 'node:test'
-import assert from 'node:assert/strict'
-import { V8CoverageService } from './v8-coverage-service.js'
-
-const service = new V8CoverageService()
-
-function coveredProbe(n: number): number {
-  return n * 2
-}
-
-describe('V8CoverageService', () => {
-  after(async () => {
-    await service.stop()
-  })
-
-  test('start + takeCoverage reports call counts for functions invoked after start', async () => {
-    await service.start()
-    coveredProbe(21)
-
-    const snapshot = await service.takeCoverage()
-    assert.equal(snapshot.kind, 'v8-scripts')
-    if (snapshot.kind !== 'v8-scripts') return
-    const own = snapshot.scripts.find((s) =>
-      s.url.includes('v8-coverage-service.test')
-    )
-    assert.ok(own, 'own test script should appear in precise coverage')
-    const probe = own.functions.find((f) =>
-      f.functionName.includes('coveredProbe')
-    )
-    assert.ok(probe, 'coveredProbe should be tracked')
-    assert.ok(
-      probe.ranges[0].count >= 1,
-      `coveredProbe should have been counted, got ${probe.ranges[0].count}`
-    )
-  })
-
-  test('reset clears call counts so attribution per run is possible', async () => {
-    coveredProbe(1)
-    await service.reset()
-    const snapshot = await service.takeCoverage()
-    if (snapshot.kind !== 'v8-scripts') return assert.fail('expected scripts')
-    const own = snapshot.scripts.find((s) =>
-      s.url.includes('v8-coverage-service.test')
-    )
-    const probe = own?.functions.find((f) =>
-      f.functionName.includes('coveredProbe')
-    )
-    const count = probe?.ranges[0].count ?? 0
-    assert.equal(
-      count,
-      0,
-      `after reset coveredProbe count should be 0, got ${count}`
-    )
-  })
-
-  test('getScriptSource returns the executed source for mapping', async () => {
-    const snapshot = await service.takeCoverage()
-    if (snapshot.kind !== 'v8-scripts') return assert.fail('expected scripts')
-    const own = snapshot.scripts.find((s) =>
-      s.url.includes('v8-coverage-service.test')
-    )
-    assert.ok(own)
-    const source = await snapshot.getScriptSource(own.scriptId)
-    assert.ok(
-      source.includes('coveredProbe'),
-      'script source should contain the probe function'
-    )
-  })
-})

package/src/services/v8-coverage-service.ts

@@ -1,163 +0,0 @@
-export interface CoverageRange {
-  startOffset: number
-  endOffset: number
-  count: number
-}
-
-export interface FunctionCoverage {
-  functionName: string
-  isBlockCoverage: boolean
-  ranges: CoverageRange[]
-}
-
-export interface ScriptCoverage {
-  scriptId: string
-  url: string
-  functions: FunctionCoverage[]
-}
-
-export type LineHits = Map<string, Map<number, number>>
-
-export type CoverageSnapshot =
-  | {
-      kind: 'v8-scripts'
-      scripts: ScriptCoverage[]
-      getScriptSource: (scriptId: string) => Promise<string>
-    }
-  | { kind: 'line-hits'; lineHits: LineHits }
-
-export type CoverageStatus = 'covered' | 'partial' | 'uncovered' | 'unknown'
-
-export interface FunctionCoverageEntry {
-  name: string
-  sourceFile: string
-  exposed: boolean
-  description: string | null
-  coveredLines: number
-  totalLines: number
-  missedLines: number[]
-  ratio: number
-  status: CoverageStatus
-}
-
-export interface FunctionCoverageReport {
-  generatedAt: string
-  summary: {
-    total: number
-    covered: number
-    partial: number
-    uncovered: number
-    unknown: number
-    overallRatio: number
-  }
-  functions: FunctionCoverageEntry[]
-}
-
-export interface CoverageFunctionMeta {
-  name: string
-  sourceFile: string
-  bodySourceFile?: string
-  exportedName?: string
-  expose?: boolean
-  description?: string | null
-  bodyStart?: number
-  bodyEnd?: number
-  funcWrapper?: string
-}
-
-export interface CoverageService {
-  start(): Promise<void>
-  takeCoverage(): Promise<CoverageSnapshot>
-  /** Provided by the process that booted the backend (the pikku CLI); absent
-   *  when the runtime only exposes raw snapshots. */
-  takeReport?(
-    functionsMeta: Record<string, CoverageFunctionMeta>
-  ): Promise<FunctionCoverageReport>
-  reset(): Promise<void>
-  stop(): Promise<void>
-}
-
-type InspectorSession = {
-  connect(): void
-  disconnect(): void
-  post(
-    method: string,
-    params?: unknown,
-    callback?: (err: Error | null, result?: any) => void
-  ): void
-}
-
-export class V8CoverageService implements CoverageService {
-  private session: InspectorSession | null = null
-  private startPromise: Promise<void> | null = null
-
-  private post<T>(method: string, params?: unknown): Promise<T> {
-    const session = this.session
-    if (!session) {
-      throw new Error('V8CoverageService not started — call start() first')
-    }
-    return new Promise<T>((resolve, reject) => {
-      session.post(method, params, (err, result) =>
-        err ? reject(err) : resolve(result as T)
-      )
-    })
-  }
-
-  start(): Promise<void> {
-    this.startPromise ??= this.doStart()
-    return this.startPromise
-  }
-
-  private async doStart(): Promise<void> {
-    // knowledge: decisions/internals/node-only-builtins-are-imported-dynamically.md
-    const inspector = await import('node:inspector')
-    this.session = new inspector.Session() as unknown as InspectorSession
-    this.session.connect()
-    await this.post('Profiler.enable')
-    await this.post('Debugger.enable')
-    await this.post('Profiler.startPreciseCoverage', {
-      callCount: true,
-      detailed: true,
-    })
-  }
-
-  async takeCoverage(): Promise<CoverageSnapshot> {
-    const { result } = await this.post<{ result: ScriptCoverage[] }>(
-      'Profiler.takePreciseCoverage'
-    )
-    return {
-      kind: 'v8-scripts',
-      scripts: result.filter((script) => script.url.startsWith('file://')),
-      getScriptSource: (scriptId) => this.getScriptSource(scriptId),
-    }
-  }
-
-  async getScriptSource(scriptId: string): Promise<string> {
-    const { scriptSource } = await this.post<{ scriptSource: string }>(
-      'Debugger.getScriptSource',
-      { scriptId }
-    )
-    return scriptSource
-  }
-
-  async reset(): Promise<void> {
-    await this.post('Profiler.stopPreciseCoverage')
-    await this.post('Profiler.startPreciseCoverage', {
-      callCount: true,
-      detailed: true,
-    })
-  }
-
-  async stop(): Promise<void> {
-    if (!this.session) return
-    try {
-      await this.post('Profiler.stopPreciseCoverage')
-      await this.post('Profiler.disable')
-      await this.post('Debugger.disable')
-    } finally {
-      this.session.disconnect()
-      this.session = null
-      this.startPromise = null
-    }
-  }
-}

package/src/services/variables-service.ts

@@ -1,13 +0,0 @@
-export interface VariablesService {
-  get<T = string>(name: string): Promise<T | undefined> | T | undefined
-  /** Same contract as `SecretService.getSecrets`: missing keys are omitted, hence `Partial<T>`. */
-  getVariables<T extends Record<string, unknown> = Record<string, unknown>>(
-    names: (keyof T & string)[]
-  ): Promise<Partial<T>> | Partial<T>
-  getAll: () =>
-    | Promise<Record<string, string | undefined>>
-    | Record<string, string | undefined>
-  set: (name: string, value: unknown) => Promise<void> | void
-  has: (name: string) => Promise<boolean> | boolean
-  delete: (name: string) => Promise<void> | void
-}

package/src/services/webhook-service.ts

@@ -1,147 +0,0 @@
-import { NotImplementedError } from '../errors/errors.js'
-import { hmacSha256Hex, timingSafeStringEqual } from '../utils/hmac.js'
-import type { Safe } from '../classification/secret-value.js'
-
-export interface SendWebhookInput {
-  url: string
-  /** Sent as the `X-Pikku-Event` header. */
-  event?: string
-  data: unknown
-  headers?: Record<string, string>
-  /** A raw HMAC key, not a secret name — overrides `config.webhook.secret`. */
-  secret?: string
-  /** Overrides `config.webhook.retries`. */
-  retries?: number
-  /** A concrete delay (`30000` or `'30s'`) selects fixed backoff; omitted means exponential. */
-  retryDelay?: string | number
-  /** Persisted only by store-backed implementations; the queue-only default ignores it. */
-  organizationId?: string
-}
-
-export interface SendWebhookResult {
-  jobId: string
-  /**
-   * The delivery row's id, which is what `getDelivery` reads back. Present only
-   * on store-backed implementations. It is not interchangeable with `jobId`: a
-   * broker is free to assign its own identity — the JetStream queue returns a
-   * stream sequence — so a caller that hands `jobId` to `getDelivery` looks up
-   * an id that was never written.
-   */
-  deliveryId?: string
-}
-
-export interface WebhookServiceConfig {
-  retries?: number
-  /** Omitted means exponential backoff. */
-  retryDelay?: string | number
-  /** A secret *name* resolved through the secret service, unlike `SendWebhookInput.secret`. */
-  secret?: string
-  signatureHeader?: string
-  /**
-   * SSRF allowlist. Set: only these hostnames may be delivered to. Omitted:
-   * private/internal hosts are blocked and every other public host is allowed.
-   */
-  allowedHosts?: string[]
-}
-
-export interface WebhookJobData {
-  url: string
-  event?: string
-  body: string
-  headers: Record<string, string>
-  /**
-   * Present only when a store-backed implementation enqueued the job. Doubles
-   * as the queue `jobId`, so it is stable across retries.
-   */
-  deliveryId?: string
-}
-
-export interface WebhookAttemptResult {
-  /** Absent when the request never completed. */
-  statusCode?: number
-  /** Truncated; captured on failure only. */
-  responseBody?: string
-  error?: string
-  delivered: boolean
-}
-
-export interface WebhookDeliveryRecord {
-  deliveryId: string
-  organizationId: string | null
-  url: string
-  event: string | null
-  status: 'pending' | 'delivered' | 'failed'
-  attempts: number
-  createdAt: Date
-  updatedAt: Date
-  deliveredAt: Date | null
-}
-
-export interface WebhookAttemptRecord {
-  attemptId: string
-  deliveryId: string
-  attemptNumber: number
-  statusCode: number | null
-  responseBody: string | null
-  error: string | null
-  createdAt: Date
-}
-
-export interface WebhookDeliveryWithAttempts {
-  delivery: WebhookDeliveryRecord
-  attempts: WebhookAttemptRecord[]
-}
-
-export const PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME = 'pikku-outgoing-webhooks'
-
-export const DEFAULT_WEBHOOK_SIGNATURE_HEADER = 'X-Pikku-Signature'
-
-export const DEFAULT_WEBHOOK_RETRIES = 3
-
-export abstract class WebhookService {
-  abstract send<T extends SendWebhookInput>(
-    input: Safe<T>
-  ): Promise<SendWebhookResult>
-
-  /** Produces the header value, `sha256=<hex>`, not the bare digest. */
-  protected sign(secret: string, body: string): string {
-    return `sha256=${hmacSha256Hex(secret, body)}`
-  }
-
-  /** Public because receivers verify with it; they share the signing scheme. */
-  public verify(secret: string, signature: string, body: string): boolean {
-    return timingSafeStringEqual(this.sign(secret, body), signature)
-  }
-
-  /**
-   * The three methods below are optional capability: the default queue-only
-   * service keeps no history and throws, and a store-backed implementation
-   * (e.g. `KyselyWebhookService` in `@pikku/kysely`) overrides them.
-   */
-  public recordAttempt(
-    _deliveryId: string,
-    _result: WebhookAttemptResult
-  ): Promise<void> {
-    throw new NotImplementedError(
-      'webhook delivery persistence is not configured'
-    )
-  }
-
-  /** Most recent first. */
-  public listDeliveries(_opts?: {
-    organizationId?: string
-    limit?: number
-  }): Promise<WebhookDeliveryRecord[]> {
-    throw new NotImplementedError(
-      'webhook delivery persistence is not configured'
-    )
-  }
-
-  public getDelivery(
-    _deliveryId: string
-  ): Promise<WebhookDeliveryWithAttempts | null> {
-    throw new NotImplementedError(
-      'webhook delivery persistence is not configured'
-    )
-  }
-}