@pikku/core 0.12.52 → 0.12.53

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

@@ -0,0 +1,66 @@
+import { describe, test, afterEach } from 'node:test'
+import assert from 'node:assert/strict'
+import { IstanbulCoverageService } from './istanbul-coverage-service.js'
+
+const FILE = '/proj/src/things.function.ts'
+
+const seedCoverage = () => {
+  ;(globalThis as any).__coverage__ = {
+    [FILE]: {
+      path: FILE,
+      statementMap: {
+        '0': { start: { line: 2, column: 2 }, end: { line: 2, column: 20 } },
+        '1': { start: { line: 3, column: 4 }, end: { line: 3, column: 30 } },
+        '2': { start: { line: 5, column: 2 }, end: { line: 6, column: 18 } },
+      },
+      s: { '0': 3, '1': 0, '2': 3 },
+      branchMap: {},
+      b: {},
+      fnMap: {},
+      f: {},
+    },
+  }
+}
+
+afterEach(() => {
+  delete (globalThis as any).__coverage__
+})
+
+describe('IstanbulCoverageService', () => {
+  test('takeCoverage converts __coverage__ statement counts into line hits', async () => {
+    seedCoverage()
+    const service = new IstanbulCoverageService()
+    await service.start()
+    const snapshot = await service.takeCoverage()
+    assert.equal(snapshot.kind, 'line-hits')
+    if (snapshot.kind !== 'line-hits') return
+    const hits = snapshot.lineHits.get(FILE)
+    assert.ok(hits, 'file should have line hits')
+    assert.equal(hits.get(2), 3)
+    assert.equal(hits.get(3), 0)
+    assert.equal(hits.get(5), 3)
+    assert.equal(
+      hits.get(6),
+      undefined,
+      'counts attach to statement start lines only'
+    )
+  })
+
+  test('reset zeroes counters so per-scenario attribution is possible', async () => {
+    seedCoverage()
+    const service = new IstanbulCoverageService()
+    await service.reset()
+    const snapshot = await service.takeCoverage()
+    if (snapshot.kind !== 'line-hits') return assert.fail('expected line-hits')
+    const hits = snapshot.lineHits.get(FILE)
+    assert.equal(hits?.get(2), 0)
+    assert.equal(hits?.get(5), 0)
+  })
+
+  test('takeCoverage with no __coverage__ global returns an empty snapshot', async () => {
+    const service = new IstanbulCoverageService()
+    const snapshot = await service.takeCoverage()
+    if (snapshot.kind !== 'line-hits') return assert.fail('expected line-hits')
+    assert.equal(snapshot.lineHits.size, 0)
+  })
+})

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

@@ -0,0 +1,65 @@
+import type {
+  CoverageService,
+  CoverageSnapshot,
+  LineHits,
+} from './v8-coverage-service.js'
+
+interface IstanbulStatementLocation {
+  start: { line: number }
+  end: { line: number }
+}
+
+interface IstanbulFileCoverage {
+  path: string
+  statementMap: Record<string, IstanbulStatementLocation>
+  s: Record<string, number>
+  b: Record<string, number[]>
+  f: Record<string, number>
+}
+
+type IstanbulCoverageGlobal = Record<string, IstanbulFileCoverage>
+
+const getCoverageGlobal = (): IstanbulCoverageGlobal | undefined =>
+  (globalThis as { __coverage__?: IstanbulCoverageGlobal }).__coverage__
+
+/**
+ * Reads istanbul-instrumented counters from the `__coverage__` global —
+ * the coverage backend for runtimes without V8 precise coverage (e.g. Bun,
+ * where source files are instrumented at load time by a Bun loader plugin).
+ */
+export class IstanbulCoverageService implements CoverageService {
+  async start(): Promise<void> {}
+
+  async takeCoverage(): Promise<CoverageSnapshot> {
+    const coverage = getCoverageGlobal()
+    const lineHits: LineHits = new Map()
+    for (const file of Object.values(coverage ?? {})) {
+      let hits = lineHits.get(file.path)
+      if (!hits) {
+        hits = new Map()
+        lineHits.set(file.path, hits)
+      }
+      // istanbul line semantics: a statement's count belongs to its start
+      // line only, so an enclosing multi-line statement never masks an
+      // unexecuted inner statement (e.g. a throw inside a taken if).
+      for (const [id, location] of Object.entries(file.statementMap)) {
+        const count = file.s[id] ?? 0
+        const line = location.start.line
+        hits.set(line, Math.max(hits.get(line) ?? 0, count))
+      }
+    }
+    return { kind: 'line-hits', lineHits }
+  }
+
+  async reset(): Promise<void> {
+    for (const file of Object.values(getCoverageGlobal() ?? {})) {
+      for (const id of Object.keys(file.s)) file.s[id] = 0
+      for (const id of Object.keys(file.f)) file.f[id] = 0
+      for (const id of Object.keys(file.b)) {
+        file.b[id] = file.b[id]!.map(() => 0)
+      }
+    }
+  }
+
+  async stop(): Promise<void> {}
+}

package/src/services/scenario-actors-service.ts

@@ -3,14 +3,7 @@ import type {
   ActorFlowVerdict,
 } from '../wirings/actor-flow/actor-flow.types.js'
 
-/**
- * A scenario actor: a synthetic user (a normal user row flagged `actor`) that
- * workflow steps can run as. Passed to `workflow.do(step, rpc, data, { actor })`
- * — the step then goes through the actor's authenticated client over the REAL
- * transport (auth middleware, permissions, serialization all exercised),
- * never through internal dispatch. Login is lazy: the first `invoke` signs the
- * actor in and the session is cached for the actor's lifetime.
- */
+/** A synthetic user (a user row flagged `actor`) that workflow steps run as over the real transport */
 export interface ScenarioActor<TAgentName extends string = string> {
   /** Stable actor name (the key in pikku.config.json's actor registry). */
   readonly name: string
@@ -18,22 +11,11 @@ export interface ScenarioActor<TAgentName extends string = string> {
   readonly email: string
   /** Invoke an exposed RPC as this actor over the real transport. */
   invoke(rpcName: string, data: unknown): Promise<unknown>
-  /**
-   * Hold a dynamic conversation with a target Pikku AI agent, in THIS actor's
-   * persona (personality/jobTitle). Drives the target over the real transport
-   * as the signed-in actor, answers its tool-approval requests in-persona, and
-   * returns the actor's verdict on whether the task was met. Deterministic
-   * checks are the caller's job — use `invoke` afterwards. In a typed project
-   * `agent` is constrained to the generated union of agent names.
-   */
+  /** Converse with a Pikku AI agent in this actor's persona and return its verdict */
   converse(options: ConverseOptions<TAgentName>): Promise<ActorFlowVerdict>
 }
 
-/**
- * Display/config metadata for an actor (from pikku.config.json). The email
- * identifies the actor's user row; personality/jobTitle exist for the console
- * screen and for agent-driven flows (the agent plays the persona).
- */
+/** Display/config metadata for an actor (from pikku.config.json) */
 export interface ScenarioActorConfig {
   email: string
   name?: string

package/src/services/stub-tracker.test.ts

@@ -0,0 +1,104 @@
+import { describe, test, beforeEach, afterEach } from 'node:test'
+import assert from 'node:assert/strict'
+import {
+  StubTracker,
+  stub,
+  spy,
+  isTestRun,
+  getStubTracker,
+} from './stub-tracker.js'
+
+describe('StubTracker', () => {
+  test('records calls and exposes them via getCalls', () => {
+    const tracker = new StubTracker()
+    tracker.record('email', 'send', [{ to: 'a@b.c' }])
+    tracker.record('payments', 'charge', [{ amount: 5 }])
+
+    assert.equal(tracker.getCalls().length, 2)
+    const emailCalls = tracker.getCalls('email')
+    assert.equal(emailCalls.length, 1)
+    assert.deepEqual(emailCalls[0], {
+      service: 'email',
+      method: 'send',
+      args: [{ to: 'a@b.c' }],
+    })
+  })
+
+  test('reset clears recorded calls and strict-mode touches', () => {
+    const tracker = new StubTracker()
+    tracker.record('email', 'send', [])
+    tracker.reset()
+    assert.equal(tracker.getCalls().length, 0)
+    tracker.verify()
+  })
+
+  test('legacy stub() proxy records through the same tracker', async () => {
+    const tracker = new StubTracker()
+    const email = tracker.stub<{ send: (msg: unknown) => Promise<void> }>(
+      'email'
+    )
+    await email.send({ to: 'x@y.z' })
+    assert.deepEqual(tracker.getCalls('email')[0]?.args, [{ to: 'x@y.z' }])
+    tracker.assert('email', 'send')
+  })
+})
+
+describe('stub/spy core utils', () => {
+  beforeEach(() => getStubTracker().reset())
+
+  test('stub() records into the default tracker and uses the implementation', async () => {
+    const email = stub<{ send: (msg: unknown) => Promise<{ ok: boolean }> }>(
+      'email',
+      { send: async () => ({ ok: true }) }
+    )
+    const result = await email.send({ to: 'a@b.c' })
+    assert.deepEqual(result, { ok: true })
+    assert.deepEqual(getStubTracker().getCalls('email')[0], {
+      service: 'email',
+      method: 'send',
+      args: [{ to: 'a@b.c' }],
+    })
+  })
+
+  test('stub() without an implementation resolves undefined', async () => {
+    const payments = stub<{ charge: (x: unknown) => Promise<unknown> }>(
+      'payments'
+    )
+    assert.equal(await payments.charge({ amount: 5 }), undefined)
+    assert.equal(getStubTracker().getCalls('payments').length, 1)
+  })
+
+  test('spy() records calls and passes through to the real service', async () => {
+    let realCalled = 0
+    const real = {
+      config: { retries: 3 },
+      send: async (msg: { to: string }) => {
+        realCalled++
+        return { delivered: msg.to }
+      },
+    }
+    const email = spy('email', real)
+
+    assert.deepEqual(await email.send({ to: 'a@b.c' }), {
+      delivered: 'a@b.c',
+    })
+    assert.equal(realCalled, 1)
+    assert.equal(email.config.retries, 3)
+    assert.equal(getStubTracker().getCalls('email').length, 1)
+  })
+})
+
+describe('isTestRun', () => {
+  const original = process.env.PIKKU_TEST_RUN
+  afterEach(() => {
+    if (original === undefined) delete process.env.PIKKU_TEST_RUN
+    else process.env.PIKKU_TEST_RUN = original
+  })
+
+  test('reflects the PIKKU_TEST_RUN environment variable', () => {
+    delete process.env.PIKKU_TEST_RUN
+    assert.equal(isTestRun(), false)
+    process.env.PIKKU_TEST_RUN = 'true'
+    assert.equal(isTestRun(), true)
+  })
+})

package/src/services/stub-tracker.ts

@@ -0,0 +1,185 @@
+export type StubCall = { service: string; method: string; args: unknown[] }
+
+type Call = { method: string; args: unknown[]; verified: boolean }
+
+/**
+ * Tracks calls made to stubbed services and enforces strict mode:
+ * once a scenario asserts any call on a service, every recorded call on that
+ * service must be verified by end of scenario — otherwise the After hook fails.
+ * Services never touched by an assertion stay 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')}`
+      )
+    }
+  }
+}
+
+/**
+ * Creates a Proxy suitable for passing as `existingServices` to
+ * `createSingletonServices`. Every property returns `tracker.stub(prop)`
+ * EXCEPT `schema`, which returns `undefined` so the service factory creates
+ * a real schema service. Stubbing the schema makes validation a no-op —
+ * required fields pass silently and tests validate nothing.
+ */
+export function createStubProxy(tracker: StubTracker): Record<string, unknown> {
+  return new Proxy({} as Record<string, unknown>, {
+    get(_, prop: string) {
+      if (prop === 'schema') return undefined
+      return tracker.stub(prop)
+    },
+  })
+}
+
+const defaultStubTracker = new StubTracker()
+
+/** The process-wide tracker that `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` (sets PIKKU_TEST_RUN) */
+export const isTestRun = (): boolean =>
+  (globalThis as { process?: { env?: Record<string, string | undefined> } })
+    .process?.env?.PIKKU_TEST_RUN === 'true'
+
+/**
+ * Creates a recording fake for a service. Methods present on `impl` run and
+ * their result is returned; missing methods resolve `undefined`. Every call
+ * is recorded so scenarios can assert via workflow.expectService().
+ */
+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/v8-coverage-service.test.ts

@@ -0,0 +1,69 @@
+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

@@ -0,0 +1,121 @@
+// node:inspector is imported lazily inside start() so this module stays
+// loadable on runtimes without it (e.g. Cloudflare Workers).
+
+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 interface CoverageService {
+  start(): Promise<void>
+  takeCoverage(): Promise<CoverageSnapshot>
+  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> {
+    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/types/core.types.ts

@@ -38,6 +38,7 @@ import type { WorkflowRunService } from '../wirings/workflow/workflow.types.js'
 import type { CredentialService } from '../services/credential-service.js'
 import type { EmailService } from '../services/email-service.js'
 import type { MetaService } from '../services/meta-service.js'
+import type { CoverageService } from '../services/v8-coverage-service.js'
 import type { SessionStore } from '../services/session-store.js'
 import type {
   AuditDurability,
@@ -150,6 +151,12 @@ export type FunctionMeta = FunctionRuntimeMeta &
       isDirectFunction: boolean
       sourceFile: string
       exportedName: string
+      /** File containing the handler body when it differs from sourceFile (imported handlers) */
+      bodySourceFile?: string
+      /** 1-indexed first line of the handler body (verbose meta; coverage mapping) */
+      bodyStart: number
+      /** 1-indexed last line of the handler body (verbose meta; coverage mapping) */
+      bodyEnd: number
     } & CommonWireMeta
   >
 
@@ -293,6 +300,8 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
   emailService?: EmailService
   /** Meta service for reading .pikku metadata files (filesystem on Node, R2/KV on CF) */
   metaService?: MetaService
+  /** V8 precise-coverage collector (`pikku dev --coverage` only) */
+  coverageService?: CoverageService
   /** Audit service for durable or staged audit event capture */
   audit?: AuditService
   /**