@pikku/core 0.12.107 → 0.12.111

package/src/wirings/workflow/run-timeline.test.ts

@@ -1,199 +0,0 @@
-import { describe, test } from 'node:test'
-import assert from 'node:assert/strict'
-
-import {
-  buildRunTimeline,
-  reconstructStateAt,
-  reconstructFinalState,
-} from './run-timeline.js'
-import type { StepState } from './workflow.types.js'
-
-type HistoryEntry = StepState & { stepName: string }
-
-const T = (ms: number) => new Date(1_700_000_000_000 + ms)
-
-const ok = (
-  stepName: string,
-  base: number,
-  opts: { from?: string; result?: unknown; attempt?: number } = {}
-): HistoryEntry =>
-  ({
-    stepId: `${stepName}-${opts.attempt ?? 1}`,
-    stepName,
-    status: 'succeeded',
-    attemptCount: opts.attempt ?? 1,
-    fromStepName: opts.from,
-    result: opts.result,
-    createdAt: T(base),
-    runningAt: T(base + 1),
-    succeededAt: T(base + 2),
-    updatedAt: T(base + 2),
-  }) as HistoryEntry
-
-const failed = (
-  stepName: string,
-  base: number,
-  opts: { from?: string; attempt?: number; message?: string } = {}
-): HistoryEntry =>
-  ({
-    stepId: `${stepName}-${opts.attempt ?? 1}`,
-    stepName,
-    status: 'failed',
-    attemptCount: opts.attempt ?? 1,
-    fromStepName: opts.from,
-    error: { message: opts.message ?? 'boom' },
-    createdAt: T(base),
-    runningAt: T(base + 1),
-    failedAt: T(base + 2),
-    updatedAt: T(base + 2),
-  }) as HistoryEntry
-
-describe('buildRunTimeline', () => {
-  test('explodes each attempt into ordered lifecycle events', () => {
-    const tl = buildRunTimeline([ok('begin', 0, { result: { n: 1 } })])
-    assert.deepEqual(
-      tl.map((e) => e.type),
-      ['pending', 'running', 'succeeded']
-    )
-    assert.deepEqual(
-      tl.map((e) => e.seq),
-      [0, 1, 2]
-    )
-    assert.deepEqual(tl[2]!.result, { n: 1 })
-    assert.equal(tl[0]!.result, undefined)
-  })
-
-  test('orders across steps by timestamp, lifecycle, then history index', () => {
-    const tl = buildRunTimeline([
-      ok('begin', 0, { result: 1 }),
-      ok('next', 2, { from: 'begin', result: 2 }),
-    ])
-    const at2 = tl.filter((e) => e.at.getTime() === T(2).getTime())
-    assert.deepEqual(
-      at2.map((e) => `${e.stepName}:${e.type}`),
-      ['next:pending', 'begin:succeeded']
-    )
-  })
-
-  test('carries provenance on the created event only', () => {
-    const tl = buildRunTimeline([ok('next', 5, { from: 'begin' })])
-    const created = tl.find((e) => e.type === 'pending')!
-    assert.equal(created.fromStepName, 'begin')
-    assert.equal(
-      tl.find((e) => e.type === 'succeeded')!.fromStepName,
-      undefined
-    )
-  })
-
-  test('terminal event is driven by status, not lifecycle timestamps', () => {
-    const noStamps = {
-      stepId: 's-1',
-      stepName: 'begin',
-      status: 'succeeded',
-      attemptCount: 1,
-      result: { ok: 1 },
-      createdAt: T(0),
-      updatedAt: T(5),
-    } as HistoryEntry
-    const tl = buildRunTimeline([noStamps])
-    assert.deepEqual(
-      tl.map((e) => e.type),
-      ['pending', 'succeeded']
-    )
-    const succeeded = tl.find((e) => e.type === 'succeeded')!
-    assert.equal(
-      succeeded.at.getTime(),
-      T(5).getTime(),
-      'falls back to updatedAt'
-    )
-    assert.deepEqual(succeeded.result, { ok: 1 })
-    assert.deepEqual(reconstructFinalState(tl).results, { begin: { ok: 1 } })
-  })
-})
-
-describe('reconstructStateAt', () => {
-  const history: HistoryEntry[] = [
-    ok('begin', 0, { result: { step: 'begin' } }),
-    ok('next', 10, { from: 'begin', result: { step: 'next' } }),
-    ok('finish', 20, { from: 'next', result: { step: 'finish' } }),
-  ]
-  const tl = buildRunTimeline(history)
-
-  test('a point before the first event is the empty initial state', () => {
-    const s = reconstructStateAt(tl, -1)
-    assert.equal(s.seq, -1)
-    assert.deepEqual(s.steps, [])
-    assert.deepEqual(s.results, {})
-    assert.equal(s.phase, 'pending')
-  })
-
-  test('mid-run by seq: only steps up to that event exist', () => {
-    const s = reconstructStateAt(tl, 2)
-    assert.deepEqual(s.path, ['begin'])
-    assert.equal(s.steps[0]!.status, 'succeeded')
-    assert.deepEqual(s.results, { begin: { step: 'begin' } })
-    assert.equal(s.phase, 'idle')
-  })
-
-  test('mid-run captures an in-flight step as running', () => {
-    const s = reconstructStateAt(tl, 4)
-    assert.deepEqual(s.path, ['begin', 'next'])
-    assert.equal(s.steps[1]!.stepName, 'next')
-    assert.equal(s.steps[1]!.status, 'running')
-    assert.equal(s.steps[1]!.fromStepName, 'begin')
-    assert.equal(s.phase, 'running')
-    assert.deepEqual(s.results, { begin: { step: 'begin' } })
-  })
-
-  test('time-travel by Date folds every event at or before the instant', () => {
-    const s = reconstructStateAt(tl, T(12))
-    assert.deepEqual(s.path, ['begin', 'next'])
-    assert.equal(s.steps[1]!.status, 'succeeded')
-    assert.deepEqual(s.results, {
-      begin: { step: 'begin' },
-      next: { step: 'next' },
-    })
-  })
-
-  test('final state has the full walked path and all results', () => {
-    const s = reconstructFinalState(tl)
-    assert.deepEqual(s.path, ['begin', 'next', 'finish'])
-    assert.deepEqual(s.results, {
-      begin: { step: 'begin' },
-      next: { step: 'next' },
-      finish: { step: 'finish' },
-    })
-    assert.equal(s.phase, 'idle')
-  })
-})
-
-describe('reconstructStateAt — retries', () => {
-  const history: HistoryEntry[] = [
-    failed('flaky', 0, { message: 'first try' }),
-    ok('flaky', 10, { result: { ok: true }, attempt: 2 }),
-  ]
-  const tl = buildRunTimeline(history)
-
-  test('between attempts the step is failed', () => {
-    const s = reconstructStateAt(tl, T(2))
-    assert.equal(s.steps[0]!.status, 'failed')
-    assert.equal(s.steps[0]!.error?.message, 'first try')
-    assert.equal(s.phase, 'failed')
-    assert.deepEqual(s.results, {})
-  })
-
-  test("the retry's created event reopens the step and clears the error", () => {
-    const s = reconstructStateAt(tl, T(10))
-    assert.equal(s.steps[0]!.status, 'pending')
-    assert.equal(s.steps[0]!.error, undefined)
-    assert.equal(s.steps[0]!.attemptCount, 2)
-    assert.equal(s.phase, 'running')
-  })
-
-  test('after the retry succeeds the result is available', () => {
-    const s = reconstructFinalState(tl)
-    assert.equal(s.steps[0]!.status, 'succeeded')
-    assert.deepEqual(s.results, { flaky: { ok: true } })
-    assert.equal(s.path.length, 1, 'a retried step is still one path entry')
-  })
-})

package/src/wirings/workflow/run-timeline.ts

@@ -1,185 +0,0 @@
-import type { SerializedError } from '../../errors/serialized-error.js'
-import type { StepState, StepStatus } from './workflow.types.js'
-
-export interface RunTimelineEvent {
-  seq: number
-  at: Date
-  type: Extract<
-    StepStatus,
-    'pending' | 'scheduled' | 'running' | 'succeeded' | 'failed'
-  >
-  stepName: string
-  attemptCount: number
-  fromStepName?: string
-  result?: unknown
-  error?: SerializedError
-}
-
-export type RunTimeline = RunTimelineEvent[]
-
-export type HistoryEntry = StepState & { stepName: string }
-
-const LIFECYCLE_ORDER: Record<RunTimelineEvent['type'], number> = {
-  pending: 0,
-  scheduled: 1,
-  running: 2,
-  succeeded: 3,
-  failed: 3,
-}
-
-export function buildRunTimeline(history: HistoryEntry[]): RunTimeline {
-  const raw: Array<Omit<RunTimelineEvent, 'seq'> & { order: number }> = []
-
-  history.forEach((entry, order) => {
-    const base = {
-      stepName: entry.stepName,
-      attemptCount: entry.attemptCount,
-      order,
-    }
-    raw.push({
-      ...base,
-      at: entry.createdAt,
-      type: 'pending',
-      fromStepName: entry.fromStepName,
-    })
-    if (entry.scheduledAt) {
-      raw.push({ ...base, at: entry.scheduledAt, type: 'scheduled' })
-    }
-    if (entry.runningAt) {
-      raw.push({ ...base, at: entry.runningAt, type: 'running' })
-    }
-    if (entry.status === 'succeeded') {
-      raw.push({
-        ...base,
-        at: entry.succeededAt ?? entry.updatedAt,
-        type: 'succeeded',
-        result: entry.result,
-      })
-    } else if (entry.status === 'failed') {
-      raw.push({
-        ...base,
-        at: entry.failedAt ?? entry.updatedAt,
-        type: 'failed',
-        error: entry.error,
-      })
-    }
-  })
-
-  raw.sort((a, b) => {
-    const ta = a.at.getTime()
-    const tb = b.at.getTime()
-    if (ta !== tb) return ta - tb
-    const la = LIFECYCLE_ORDER[a.type]
-    const lb = LIFECYCLE_ORDER[b.type]
-    if (la !== lb) return la - lb
-    return a.order - b.order
-  })
-
-  return raw.map(({ order: _order, ...event }, seq) => ({ ...event, seq }))
-}
-
-export interface ReconstructedStep {
-  stepName: string
-  status: StepStatus
-  attemptCount: number
-  fromStepName?: string
-  result?: unknown
-  error?: SerializedError
-}
-
-export type RunPhase = 'pending' | 'running' | 'failed' | 'idle'
-
-export interface ReconstructedRunState {
-  /** seq of the last applied event, or -1 if the point precedes all events. */
-  seq: number
-  at?: Date
-  steps: ReconstructedStep[]
-  results: Record<string, unknown>
-  path: string[]
-  phase: RunPhase
-}
-
-const IN_FLIGHT: ReadonlySet<StepStatus> = new Set([
-  'pending',
-  'scheduled',
-  'running',
-])
-
-export function reconstructStateAt(
-  timeline: RunTimeline,
-  at: number | Date
-): ReconstructedRunState {
-  const cutoff = (event: RunTimelineEvent): boolean =>
-    typeof at === 'number'
-      ? event.seq <= at
-      : event.at.getTime() <= at.getTime()
-
-  const steps = new Map<string, ReconstructedStep>()
-  const path: string[] = []
-  let lastSeq = -1
-  let lastAt: Date | undefined
-
-  for (const event of timeline) {
-    if (!cutoff(event)) break
-    lastSeq = event.seq
-    lastAt = event.at
-
-    let step = steps.get(event.stepName)
-    if (!step) {
-      step = {
-        stepName: event.stepName,
-        status: event.type,
-        attemptCount: event.attemptCount,
-        fromStepName: event.fromStepName,
-      }
-      steps.set(event.stepName, step)
-      path.push(event.stepName)
-    }
-    step.status = event.type
-    step.attemptCount = event.attemptCount
-    if (event.fromStepName !== undefined) {
-      step.fromStepName = event.fromStepName
-    }
-    if (event.type === 'pending') {
-      delete step.result
-      delete step.error
-    }
-    if (event.type === 'succeeded') {
-      step.result = event.result
-      step.error = undefined
-    }
-    if (event.type === 'failed') {
-      step.error = event.error
-    }
-  }
-
-  const orderedSteps = path.map((name) => steps.get(name)!)
-  const results: Record<string, unknown> = {}
-  for (const step of orderedSteps) {
-    if (step.status === 'succeeded') {
-      results[step.stepName] = step.result
-    }
-  }
-
-  return {
-    seq: lastSeq,
-    at: lastAt,
-    steps: orderedSteps,
-    results,
-    path,
-    phase: derivePhase(orderedSteps),
-  }
-}
-
-export function reconstructFinalState(
-  timeline: RunTimeline
-): ReconstructedRunState {
-  return reconstructStateAt(timeline, timeline.length - 1)
-}
-
-function derivePhase(steps: ReconstructedStep[]): RunPhase {
-  if (steps.length === 0) return 'pending'
-  if (steps.some((s) => IN_FLIGHT.has(s.status))) return 'running'
-  if (steps.some((s) => s.status === 'failed')) return 'failed'
-  return 'idle'
-}

package/src/wirings/workflow/scenario-cookie-jar.test.ts

@@ -1,107 +0,0 @@
-import { describe, test, after } from 'node:test'
-import assert from 'node:assert/strict'
-import { createServer, type Server } from 'node:http'
-
-import { createCookieJar } from './scenario-cookie-jar.js'
-
-const startTarget = async () => {
-  let issued = 0
-  const server: Server = createServer((req, res) => {
-    if (req.url === '/set') {
-      issued++
-      res.setHeader('set-cookie', [
-        `session=s${issued}; Path=/; HttpOnly`,
-        `csrf=c${issued}; Path=/`,
-      ])
-      res.writeHead(200, { 'content-type': 'application/json' }).end('{}')
-      return
-    }
-    res.writeHead(200, { 'content-type': 'application/json' }).end(
-      JSON.stringify({
-        cookie: req.headers.cookie ?? '',
-        origin: req.headers.origin ?? '',
-      })
-    )
-  })
-  await new Promise<void>((done) => server.listen(0, '127.0.0.1', done))
-  const { port } = server.address() as { port: number }
-  return { server, apiUrl: `http://127.0.0.1:${port}` }
-}
-
-describe('createCookieJar', () => {
-  test('sends back the cookies the target set, on the next request', async () => {
-    const { server, apiUrl } = await startTarget()
-    after(() => server.close())
-
-    const { fetch: call } = createCookieJar(apiUrl)
-    await call(`${apiUrl}/set`)
-    const seen = await (await call(`${apiUrl}/echo`)).json()
-
-    assert.match(seen.cookie, /session=s1/)
-    assert.match(seen.cookie, /csrf=c1/)
-  })
-
-  test('stamps the origin Better Auth checks on state-changing calls', async () => {
-    const { server, apiUrl } = await startTarget()
-    after(() => server.close())
-
-    const seen = await (
-      await createCookieJar(apiUrl).fetch(`${apiUrl}/echo`)
-    ).json()
-
-    assert.equal(seen.origin, apiUrl)
-  })
-
-  test('replaces a cookie the target reissues rather than sending both', async () => {
-    const { server, apiUrl } = await startTarget()
-    after(() => server.close())
-
-    const { fetch: call } = createCookieJar(apiUrl)
-    await call(`${apiUrl}/set`)
-    await call(`${apiUrl}/set`)
-    const seen = await (await call(`${apiUrl}/echo`)).json()
-
-    assert.match(seen.cookie, /session=s2/)
-    assert.doesNotMatch(seen.cookie, /session=s1/)
-  })
-
-  test('keeps each jar to itself, so one actor never inherits another session', async () => {
-    const { server, apiUrl } = await startTarget()
-    after(() => server.close())
-
-    const first = createCookieJar(apiUrl)
-    await first.fetch(`${apiUrl}/set`)
-    const other = await (
-      await createCookieJar(apiUrl).fetch(`${apiUrl}/echo`)
-    ).json()
-
-    assert.equal(other.cookie, '')
-  })
-
-  test('forgets the session when cleared, so a re-login starts fresh', async () => {
-    const { server, apiUrl } = await startTarget()
-    after(() => server.close())
-
-    const jar = createCookieJar(apiUrl)
-    await jar.fetch(`${apiUrl}/set`)
-    assert.equal(jar.empty, false)
-    jar.clear()
-    assert.equal(jar.empty, true)
-
-    const seen = await (await jar.fetch(`${apiUrl}/echo`)).json()
-    assert.equal(seen.cookie, '')
-  })
-
-  test('leaves the caller headers alone', async () => {
-    const { server, apiUrl } = await startTarget()
-    after(() => server.close())
-
-    const headers = new Headers({ 'x-test': 'kept' })
-    const { fetch: call } = createCookieJar(apiUrl)
-    await call(`${apiUrl}/set`)
-    await call(`${apiUrl}/echo`, { headers })
-
-    assert.equal(headers.get('cookie'), null)
-    assert.equal(headers.get('x-test'), 'kept')
-  })
-})

package/src/wirings/workflow/scenario-cookie-jar.ts

@@ -1,57 +0,0 @@
-export interface ScenarioCookieJar {
-  fetch: typeof fetch
-  clear(): void
-  readonly empty: boolean
-}
-
-/**
- * A cookie store for a scenario run, so a step that signs in leaves the session
- * cookie behind for the steps after it.
- *
- * @example snippet: scenarioCookieJar
- */
-export const createCookieJar = (apiUrl: string): ScenarioCookieJar => {
-  const jar = new Map<string, string>()
-  const origin = new URL(apiUrl).origin
-  return {
-    fetch: async (input, init) => {
-      const headers = new Headers(init?.headers)
-      headers.set('origin', origin)
-      // The caller's own cookie header wins per name: a request that already
-      // carries a session is stating which one it means, and emitting the jar's
-      // copy alongside it sends the same name twice.
-      const caller = headers.get('cookie')
-      const named = new Set(
-        (caller ?? '')
-          .split(';')
-          .map((pair) => pair.split('=')[0]?.trim())
-          .filter(Boolean)
-      )
-      const held = [...jar]
-        .filter(([name]) => !named.has(name))
-        .map(([name, value]) => `${name}=${value}`)
-      if (held.length > 0 || caller) {
-        headers.set('cookie', [caller, ...held].filter(Boolean).join('; '))
-      }
-      const response = await fetch(input, { ...init, headers })
-      for (const raw of response.headers.getSetCookie()) {
-        const [pair] = raw.split(';')
-        const separator = pair!.indexOf('=')
-        if (separator > 0) {
-          const name = pair!.slice(0, separator)
-          const value = pair!.slice(separator + 1)
-          if (value) {
-            jar.set(name, value)
-          } else {
-            jar.delete(name)
-          }
-        }
-      }
-      return response
-    },
-    clear: () => jar.clear(),
-    get empty() {
-      return jar.size === 0
-    },
-  }
-}