@pikku/core 0.12.106 → 0.12.111

package/src/services/stub-tracker.ts

@@ -1,175 +0,0 @@
-export type StubCall = { service: string; method: string; args: unknown[] }
-
-type Call = { method: string; args: unknown[]; verified: boolean }
-
-/**
- * Strict per service: once a scenario asserts any call on a service, every
- * recorded call on it must be verified by the end of the scenario or the After
- * hook fails. A service no assertion ever touched stays lenient.
- */
-export class StubTracker {
-  private readonly calls = new Map<string, Call[]>()
-  private readonly touched = new Set<string>()
-
-  record(service: string, method: string, args: unknown[]): void {
-    const list = this.calls.get(service) ?? []
-    list.push({ method, args, verified: false })
-    this.calls.set(service, list)
-  }
-
-  getCalls(service?: string): StubCall[] {
-    const result: StubCall[] = []
-    for (const [name, list] of this.calls) {
-      if (service && name !== service) continue
-      for (const call of list) {
-        result.push({ service: name, method: call.method, args: call.args })
-      }
-    }
-    return result
-  }
-
-  reset(): void {
-    this.calls.clear()
-    this.touched.clear()
-  }
-
-  stub<T>(service: string): T {
-    const self = this
-    return new Proxy(Object.create(null) as object, {
-      get(_, method: string) {
-        return (...args: unknown[]) => {
-          self.record(service, method, args)
-          return Promise.resolve()
-        }
-      },
-    }) as unknown as T
-  }
-
-  assert(service: string, method: string): void {
-    this.touched.add(service)
-    const list = this.calls.get(service) ?? []
-    const idx = list.findIndex((c) => c.method === method && !c.verified)
-    if (idx === -1) {
-      const seen = list.map((c) => c.method).join(', ') || '(none)'
-      throw new Error(
-        `Expected "${service}.${method}" to have been called. Recorded: ${seen}`
-      )
-    }
-    list[idx]!.verified = true
-  }
-
-  assertCall(
-    service: string,
-    method: string,
-    predicate: (args: unknown[]) => boolean,
-    description: string
-  ): void {
-    this.touched.add(service)
-    const list = this.calls.get(service) ?? []
-    const idx = list.findIndex(
-      (c) => c.method === method && !c.verified && predicate(c.args)
-    )
-    if (idx === -1) {
-      const seen =
-        list
-          .filter((c) => c.method === method)
-          .map((c) => JSON.stringify(c.args[0]))
-          .join('\n  ') || '(none)'
-      throw new Error(`Expected ${description} but found:\n  ${seen}`)
-    }
-    list[idx]!.verified = true
-  }
-
-  assertNoCalls(
-    service: string,
-    method?: string,
-    predicate?: (args: unknown[]) => boolean,
-    description?: string
-  ): void {
-    this.touched.add(service)
-    const list = this.calls.get(service) ?? []
-    const relevant = (
-      method ? list.filter((c) => c.method === method) : list
-    ).filter((c) => !predicate || predicate(c.args))
-    if (relevant.length > 0) {
-      const calls = relevant
-        .map(
-          (c) =>
-            `${c.method}(${c.args.map((a) => JSON.stringify(a)).join(', ')})`
-        )
-        .join('\n  ')
-      const what = description ?? `"${service}${method ? '.' + method : ''}"`
-      throw new Error(`Expected no ${what} calls but got:\n  ${calls}`)
-    }
-  }
-
-  verify(): void {
-    const errors: string[] = []
-    for (const service of this.touched) {
-      const unverified = (this.calls.get(service) ?? []).filter(
-        (c) => !c.verified
-      )
-      for (const c of unverified) {
-        const argStr = c.args.map((a) => JSON.stringify(a)).join(', ')
-        errors.push(`  ${service}.${c.method}(${argStr})`)
-      }
-    }
-    if (errors.length) {
-      throw new Error(
-        `Unexpected stub calls — assert them in the scenario or remove the side effect:\n${errors.join('\n')}`
-      )
-    }
-  }
-}
-
-/** Pass as `existingServices` to `createSingletonServices`. */
-export function createStubProxy(tracker: StubTracker): Record<string, unknown> {
-  return new Proxy({} as Record<string, unknown>, {
-    get(_, prop: string) {
-      // knowledge: decisions/internals/the-schema-service-is-never-stubbed.md
-      if (prop === 'schema') return undefined
-      return tracker.stub(prop)
-    },
-  })
-}
-
-const defaultStubTracker = new StubTracker()
-
-/** The process-wide tracker `stub()`/`spy()` record into; read by the console's getStubCalls/resetStubs RPCs. */
-export const getStubTracker = (): StubTracker => defaultStubTracker
-
-/** True when the server was started by `pikku dev --test`, which sets PIKKU_TEST_RUN. */
-export const isTestRun = (): boolean =>
-  (globalThis as { process?: { env?: Record<string, string | undefined> } })
-    .process?.env?.PIKKU_TEST_RUN === 'true'
-
-/** Methods on `impl` run and return; every other method resolves `undefined`. */
-export function stub<T = any>(service: string, impl?: Partial<T>): T {
-  return new Proxy((impl ?? {}) as object, {
-    get(target: any, method: string | symbol) {
-      if (typeof method === 'symbol') return target[method]
-      const real = target[method]
-      if (typeof real !== 'function' && real !== undefined) return real
-      return (...args: unknown[]) => {
-        defaultStubTracker.record(service, method, args)
-        return real ? real.apply(target, args) : Promise.resolve(undefined)
-      }
-    },
-  }) as T
-}
-
-/** Wraps a real service so every method call is recorded and passed through */
-export function spy<T extends object>(service: string, real: T): T {
-  return new Proxy(real, {
-    get(target: any, method: string | symbol) {
-      const value = target[method]
-      if (typeof method === 'symbol' || typeof value !== 'function') {
-        return value
-      }
-      return (...args: unknown[]) => {
-        defaultStubTracker.record(service, method, args)
-        return value.apply(target, args)
-      }
-    },
-  }) as T
-}

package/src/services/system-role-guard.test.ts

@@ -1,96 +0,0 @@
-import { describe, test } from 'node:test'
-import assert from 'node:assert/strict'
-
-import {
-  assertRoleIsMutable,
-  assertRoleNameAvailable,
-  roleLockReason,
-} from './system-role-guard.js'
-import {
-  SystemRoleImmutableError,
-  SystemRoleShadowedError,
-} from '../errors/errors.js'
-
-const system =
-  (...names: string[]) =>
-  (name: string) =>
-    names.includes(name)
-
-describe('mutating a role', () => {
-  test('a declared role refuses to be deleted or re-scoped', async () => {
-    await assert.rejects(
-      () => assertRoleIsMutable('buyer', system('buyer'), 'delete role'),
-      SystemRoleImmutableError
-    )
-  })
-
-  test('the refusal says which role and what was attempted', async () => {
-    await assert.rejects(
-      () => assertRoleIsMutable('buyer', system('buyer'), 'set scopes on'),
-      /Cannot set scopes on 'buyer'[\s\S]*defineSystemRole/
-    )
-  })
-
-  test('a custom role is left alone', async () => {
-    await assert.doesNotReject(() =>
-      assertRoleIsMutable('invoicing-clerk', system('buyer'), 'delete role')
-    )
-  })
-
-  test('an async lookup is awaited, not truthy-tested', async () => {
-    await assert.rejects(
-      () => assertRoleIsMutable('buyer', async () => true, 'delete role'),
-      SystemRoleImmutableError
-    )
-    // A promise resolving to false is itself truthy — the guard must await it
-    // rather than treat the promise as the answer.
-    await assert.doesNotReject(() =>
-      assertRoleIsMutable('buyer', async () => false, 'delete role')
-    )
-  })
-})
-
-describe('creating a role', () => {
-  test('shadowing a declared name is refused', async () => {
-    await assert.rejects(
-      () => assertRoleNameAvailable('buyer', system('buyer')),
-      SystemRoleShadowedError
-    )
-  })
-
-  test('an unused name is allowed', async () => {
-    await assert.doesNotReject(() =>
-      assertRoleNameAvailable('invoicing-clerk', system('buyer'))
-    )
-  })
-})
-
-describe('what the console renders', () => {
-  test('a custom role has no lock', () => {
-    assert.equal(roleLockReason({ name: 'clerk', scopes: [] }), null)
-  })
-
-  test('a declared role locks with the reason and the fix', () => {
-    const reason = roleLockReason({
-      name: 'buyer',
-      scopes: [],
-      system: true,
-      declared: true,
-    })
-    assert.match(reason!, /declared in code with defineSystemRole/)
-  })
-
-  // An undeclared system role is still locked, but for a different reason and
-  // with a different fix — saying "edit the declaration" would send someone
-  // looking for a declaration that no longer exists.
-  test('an undeclared system role explains that it is inert', () => {
-    const reason = roleLockReason({
-      name: 'buyer',
-      scopes: [],
-      system: true,
-      declared: false,
-    })
-    assert.match(reason!, /inert/)
-    assert.match(reason!, /pikku roles prune/)
-  })
-})

package/src/services/system-role-guard.ts

@@ -1,71 +0,0 @@
-import {
-  SystemRoleImmutableError,
-  SystemRoleShadowedError,
-} from '../errors/errors.js'
-import type { Role } from './scope-service.js'
-
-/**
- * The guards a {@link ScopeService} implementation must apply before mutating
- * a role.
- *
- * Shared rather than left to each implementation because the rule is a
- * contract, not a policy: a store that lets the console delete `buyer` makes
- * every persona and scenario written against `buyer` silently stop testing
- * what it claims to, and nothing fails at the point of the mistake. Two
- * implementations disagreeing about that would be worse than either rule.
- *
- * `isSystemRole` is passed in rather than a role list, so an implementation can
- * answer it from a column, a cached set, or a query, whichever is cheap.
- */
-export type IsSystemRole = (name: string) => boolean | Promise<boolean>
-
-/**
- * Refuses a destructive or re-scoping operation against a declared role.
- *
- * @param operation a verb phrase for the message, e.g. `'delete role'`.
- */
-export const assertRoleIsMutable = async (
-  name: string,
-  isSystemRole: IsSystemRole,
-  operation: string
-): Promise<void> => {
-  if (await isSystemRole(name)) {
-    throw new SystemRoleImmutableError(name, operation)
-  }
-}
-
-/**
- * Refuses a new custom role that would shadow a declared one.
- */
-export const assertRoleNameAvailable = async (
-  name: string,
-  isSystemRole: IsSystemRole
-): Promise<void> => {
-  if (await isSystemRole(name)) {
-    throw new SystemRoleShadowedError(name)
-  }
-}
-
-/**
- * Why the console must render a role as locked, or `null` when it is editable.
- *
- * Returned rather than a boolean so the UI shows a reason instead of a
- * disabled button with no explanation — the difference between a user filing a
- * bug and a user editing the declaration.
- */
-export const roleLockReason = (role: Role): string | null => {
-  if (!role.system) {
-    return null
-  }
-  if (role.declared === false) {
-    return (
-      `'${role.name}' was declared in code and that declaration has been removed. ` +
-      `It is inert: still held by its current members, not offered for new grants. ` +
-      `Run 'pikku roles prune' to remove it.`
-    )
-  }
-  return (
-    `'${role.name}' is declared in code with defineSystemRole. ` +
-    `Edit the declaration to change what it grants.`
-  )
-}

package/src/services/temporary-file-service.ts

@@ -1,76 +0,0 @@
-import { createReadStream, createWriteStream } from 'fs'
-import { mkdir, rm, stat } from 'fs/promises'
-import { resolve } from 'path'
-import { pipeline } from 'stream/promises'
-import type { Readable } from 'stream'
-import type { Logger } from './logger.js'
-
-export class TemporaryFileInstance {
-  private files: string[] = []
-
-  constructor(
-    private logger: Logger,
-    private tempDir: string
-  ) {
-    this.tempDir = resolve(tempDir)
-    logger.debug(`Using temp dir ${this.tempDir}`)
-  }
-
-  public getFile(key: string): ReadableStream | NodeJS.ReadableStream {
-    return createReadStream(`${this.tempDir}/${key}`)
-  }
-
-  public async writeFile(
-    key: string,
-    stream: ReadableStream | NodeJS.ReadableStream
-  ): Promise<void> {
-    await this.createDir(key)
-    const filePath = `${this.tempDir}/${key}`
-    const fileStream = createWriteStream(filePath)
-    await pipeline(stream as Readable, fileStream)
-    this.files.push(filePath)
-    this.logger.debug(`Wrote file: ${filePath}`)
-  }
-
-  public async deleteFile(key: string): Promise<void> {
-    await rm(`${this.tempDir}/${key}`)
-    this.logger.debug(`Deleted file ${this.tempDir}/${key}`)
-  }
-
-  public async hasFile(key: string): Promise<boolean> {
-    try {
-      return !!(await stat(`${this.tempDir}/${key}`))
-    } catch {
-      return false
-    }
-  }
-
-  public async getTempFileAbsolutePath(key: string): Promise<string> {
-    await this.createDir(key)
-    return `${this.tempDir}/${key}`
-  }
-
-  private async createDir(key: string) {
-    const dir = `${this.tempDir}/${key}`.split('/').slice(0, -1).join('/')
-    if (!(await this.hasFile(dir))) {
-      await mkdir(dir, { recursive: true })
-    }
-  }
-
-  public async cleanup() {
-    await Promise.all(this.files.map((file) => rm(file)))
-  }
-}
-
-export class TemporaryFileService {
-  constructor(
-    private logger: Logger,
-    private tempDir: string
-  ) {
-    this.tempDir = resolve(tempDir)
-  }
-
-  public createInstance() {
-    return new TemporaryFileInstance(this.logger, this.tempDir)
-  }
-}

package/src/services/trigger-service.ts

@@ -1,5 +0,0 @@
-export interface TriggerService {
-  start(): Promise<void>
-
-  stop(): Promise<void>
-}

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

@@ -1,83 +0,0 @@
-import type { CredentialService } from './credential-service.js'
-
-export interface CredentialStatusInfo {
-  name: string
-  displayName: string
-  isConfigured: boolean
-  type: 'singleton' | 'wire'
-  oauth2?: boolean
-}
-
-export type CredentialMetaInfo = {
-  name: string
-  displayName: string
-  type: 'singleton' | 'wire'
-  oauth2?: boolean
-}
-
-export class TypedCredentialService<
-  TMap = Record<string, unknown>,
-> implements CredentialService {
-  constructor(
-    private credentials: CredentialService,
-    private credentialsMeta: Record<string, CredentialMetaInfo>
-  ) {}
-
-  async get<K extends keyof TMap & string>(
-    name: K,
-    userId?: string
-  ): Promise<TMap[K] | null>
-  async get<T = unknown>(name: string, userId?: string): Promise<T | null>
-  async get(name: string, userId?: string): Promise<unknown> {
-    return this.credentials.get(name, userId)
-  }
-
-  async set<K extends string>(
-    name: K,
-    value: K extends keyof TMap ? TMap[K] : unknown,
-    userId?: string
-  ): Promise<void> {
-    return this.credentials.set(name, value, userId)
-  }
-
-  async delete(name: string, userId?: string): Promise<void> {
-    return this.credentials.delete(name, userId)
-  }
-
-  async has(name: string, userId?: string): Promise<boolean> {
-    return this.credentials.has(name, userId)
-  }
-
-  async getAll(userId: string): Promise<Record<string, unknown>> {
-    return this.credentials.getAll(userId)
-  }
-
-  async getUsersWithCredential(name: string): Promise<string[]> {
-    return this.credentials.getUsersWithCredential(name)
-  }
-
-  async getAllUsers(): Promise<string[]> {
-    return this.credentials.getAllUsers()
-  }
-
-  async getAllStatus(userId?: string): Promise<CredentialStatusInfo[]> {
-    const results: CredentialStatusInfo[] = []
-
-    for (const [name, meta] of Object.entries(this.credentialsMeta)) {
-      results.push({
-        name,
-        displayName: meta.displayName,
-        isConfigured: await this.credentials.has(name, userId),
-        type: meta.type,
-        oauth2: meta.oauth2,
-      })
-    }
-
-    return results
-  }
-
-  async getMissing(userId?: string): Promise<CredentialStatusInfo[]> {
-    const all = await this.getAllStatus(userId)
-    return all.filter((c) => !c.isConfigured)
-  }
-}