@pikku/core 0.12.69 → 0.12.70

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

@@ -0,0 +1,108 @@
+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'
+
+// Minimal target: hands out cookies, and reports back what it was sent.
+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

@@ -0,0 +1,65 @@
+/** A session held the way a browser holds one, for code driving a real target. */
+export interface ScenarioCookieJar {
+  /** `fetch`, but it sends what the target has set and keeps what it sets. */
+  fetch: typeof fetch
+  /** Forgets the session — what an actor does before signing in again. */
+  clear(): void
+  /**
+   * Whether the target has set anything yet. This is a fact about the jar, not
+   * about the session: a target that sets a CSRF or locale cookie before anyone
+   * signs in fills the jar without establishing one. Whoever needs to know
+   * whether a sign-in happened has to track the sign-in.
+   */
+  readonly empty: boolean
+}
+
+/**
+ * A `fetch` that remembers cookies.
+ *
+ * A browser persists the session cookie on its own; anything driving a target
+ * from this process has to. Every response is read, not just the sign-in, so a
+ * cookie the target rotates mid-session is followed rather than dropped.
+ *
+ * The jar is a closure local, so two jars never share a session — which is what
+ * lets one scenario sign in as several people without one of them inheriting
+ * the other's session.
+ *
+ * It also stamps `Origin`, because Better Auth rejects a state-changing POST
+ * whose Origin does not match its baseURL.
+ */
+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)
+      const held = [...jar].map(([name, value]) => `${name}=${value}`)
+      const caller = headers.get('cookie')
+      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)
+          // An empty value is how a target deletes a cookie — drop the name
+          // rather than holding a cookie whose value says it is gone.
+          if (value) {
+            jar.set(name, value)
+          } else {
+            jar.delete(name)
+          }
+        }
+      }
+      return response
+    },
+    clear: () => jar.clear(),
+    get empty() {
+      return jar.size === 0
+    },
+  }
+}

package/src/wirings/workflow/scenario-hooks.test.ts

@@ -0,0 +1,212 @@
+import { describe, test, beforeEach } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { createScenarioRunner } from './pikku-scenario-service.js'
+import { pikkuState, resetPikkuState } from '../../pikku-state.js'
+import { addWorkflow } from './dsl/workflow-runner.js'
+import type { ScenarioActors } from '../../services/scenario-actors-service.js'
+
+const noopLogger = {
+  error() {},
+  info() {},
+  warn() {},
+  debug() {},
+}
+
+const actors = {
+  admin: {
+    name: 'admin',
+    email: 'admin@actors.local',
+    invoke: async () => ({}),
+    invokeRaw: async () => ({ status: 200, ok: true, body: {} }),
+  },
+} as unknown as ScenarioActors
+
+type ScenarioHooks = {
+  before?: (services: any, data: any, wire: any) => Promise<void> | void
+  after?: (services: any, data: any, wire: any) => Promise<void> | void
+}
+
+/**
+ * Registers a scenario (or, with `source: 'dsl'`, a plain workflow) and runs it
+ * inline, returning the error it threw rather than propagating — every hook
+ * assertion here is about what ran, not about how the caller saw it.
+ */
+const runScenario = async (
+  name: string,
+  config: ScenarioHooks & { func: (...args: any[]) => any },
+  { input = {}, source = 'scenario' as 'scenario' | 'dsl' } = {}
+) => {
+  const { workflowService: ws, scenarioService } = createScenarioRunner()
+
+  pikkuState(null, 'package', 'singletonServices', {
+    logger: noopLogger,
+    marker: 'singleton',
+  } as any)
+
+  const metaState = pikkuState(null, 'workflows', 'meta')
+  metaState[name] = {
+    name,
+    pikkuFuncId: name,
+    source,
+    graphHash: `${name}-hash`,
+  } as any
+
+  const functionMetaState = pikkuState(null, 'function', 'meta')
+  functionMetaState[name] = {
+    name,
+    sessionless: true,
+    permissions: [],
+  } as any
+
+  addWorkflow(name, config as any)
+
+  let error: any
+  try {
+    await ws.startWorkflow(name, input, {} as any, {}, { actors })
+  } catch (e: any) {
+    error = e
+  }
+  const runs = await ws.listRuns({ workflowName: name })
+  const run = runs[0]
+  return { error, run, ws }
+}
+
+describe('scenario before/after hooks', () => {
+  beforeEach(() => resetPikkuState())
+
+  test('before runs, then the scenario, then after', async () => {
+    const order: string[] = []
+    await runScenario('hooksOrder', {
+      before: async () => {
+        order.push('before')
+      },
+      after: async () => {
+        order.push('after')
+      },
+      func: async () => {
+        order.push('func')
+        return { ok: true }
+      },
+    })
+    assert.deepEqual(order, ['before', 'func', 'after'])
+  })
+
+  test('after still runs when the scenario throws', async () => {
+    const order: string[] = []
+    const { error, run } = await runScenario('hooksAfterOnFailure', {
+      after: async () => {
+        order.push('after')
+      },
+      func: async () => {
+        order.push('func')
+        throw new Error('scenario blew up')
+      },
+    })
+    assert.deepEqual(order, ['func', 'after'])
+    assert.equal(error?.message, 'scenario blew up')
+    assert.equal(run?.status, 'failed')
+  })
+
+  test('before throwing skips the scenario but still runs after', async () => {
+    const order: string[] = []
+    const { error, run } = await runScenario('hooksBeforeThrows', {
+      before: async () => {
+        order.push('before')
+        throw new Error('setup failed')
+      },
+      after: async () => {
+        order.push('after')
+      },
+      func: async () => {
+        order.push('func')
+        return { ok: true }
+      },
+    })
+    assert.deepEqual(order, ['before', 'after'], 'the func must not run')
+    assert.match(String(error?.message), /setup failed/)
+    assert.equal(run?.status, 'failed')
+  })
+
+  test('after throwing fails a run that would otherwise have passed', async () => {
+    const { error, run } = await runScenario('hooksAfterThrows', {
+      after: async () => {
+        throw new Error('teardown failed')
+      },
+      func: async () => ({ ok: true }),
+    })
+    assert.match(String(error?.message), /teardown failed/)
+    assert.equal(run?.status, 'failed')
+  })
+
+  test('after throwing never masks the original failure', async () => {
+    const { error } = await runScenario('hooksAfterMasks', {
+      after: async () => {
+        throw new Error('teardown failed')
+      },
+      func: async () => {
+        throw new Error('the real failure')
+      },
+    })
+    assert.equal(
+      error?.message,
+      'the real failure',
+      'the scenario failure must be what the caller sees'
+    )
+    assert.match(
+      String((error as any)?.cause?.message),
+      /teardown failed/,
+      'the teardown failure must survive as the cause'
+    )
+  })
+
+  test('hooks receive the services, the input and the run actors', async () => {
+    const seen: any[] = []
+    await runScenario(
+      'hooksArgs',
+      {
+        before: async (services, data, wire) => {
+          seen.push({
+            marker: services.marker,
+            data,
+            actor: wire?.actors?.admin?.name,
+          })
+        },
+        after: async (services, data, wire) => {
+          seen.push({
+            marker: services.marker,
+            data,
+            actor: wire?.actors?.admin?.name,
+          })
+        },
+        func: async () => ({ ok: true }),
+      },
+      { input: { seed: 7 } }
+    )
+    assert.deepEqual(seen, [
+      { marker: 'singleton', data: { seed: 7 }, actor: 'admin' },
+      { marker: 'singleton', data: { seed: 7 }, actor: 'admin' },
+    ])
+  })
+
+  test('hooks are scenario-only — a plain DSL workflow never runs them', async () => {
+    const order: string[] = []
+    await runScenario(
+      'hooksNotForWorkflows',
+      {
+        before: async () => {
+          order.push('before')
+        },
+        after: async () => {
+          order.push('after')
+        },
+        func: async () => {
+          order.push('func')
+          return { ok: true }
+        },
+      },
+      { source: 'dsl' }
+    )
+    assert.deepEqual(order, ['func'])
+  })
+})

package/src/wirings/workflow/scenario-poll.test.ts

@@ -0,0 +1,66 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { pollUntil } from './scenario-poll.js'
+
+describe('pollUntil', () => {
+  test('answers with the first attempt that produced something', async () => {
+    let attempts = 0
+    const found = await pollUntil(
+      () => {
+        attempts++
+        return attempts === 3 ? 'ready' : undefined
+      },
+      { intervalMs: 1 }
+    )
+
+    assert.equal(found, 'ready')
+    assert.equal(attempts, 3)
+  })
+
+  test('gives up at the deadline rather than looping forever', async () => {
+    const started = Date.now()
+    const found = await pollUntil(() => undefined, {
+      timeoutMs: 30,
+      intervalMs: 5,
+    })
+
+    assert.equal(found, undefined)
+    assert.ok(Date.now() - started < 1_000, 'returned promptly')
+  })
+
+  test('always attempts at least once, however short the deadline', async () => {
+    let attempts = 0
+    const found = await pollUntil(
+      () => {
+        attempts++
+        return 'immediate'
+      },
+      { timeoutMs: 0 }
+    )
+
+    assert.equal(attempts, 1)
+    assert.equal(found, 'immediate')
+  })
+
+  test('awaits an async attempt', async () => {
+    const found = await pollUntil(async () => 'awaited', { intervalMs: 1 })
+    assert.equal(found, 'awaited')
+  })
+
+  test('treats a falsy-but-defined answer as an answer', async () => {
+    // `false` is what a "did it happen?" probe returns, and it is a result —
+    // only `undefined` means "not yet".
+    let attempts = 0
+    const found = await pollUntil(
+      () => {
+        attempts++
+        return false
+      },
+      { timeoutMs: 50, intervalMs: 1 }
+    )
+
+    assert.equal(found, false)
+    assert.equal(attempts, 1)
+  })
+})

package/src/wirings/workflow/scenario-poll.ts

@@ -0,0 +1,36 @@
+/** How long to keep trying, and how long to wait between tries. */
+export interface PollOptions {
+  /** Total time to keep attempting before giving up. Default 15s. */
+  timeoutMs?: number
+  /** Gap between attempts. Default 250ms. */
+  intervalMs?: number
+}
+
+/**
+ * Attempt something until it answers, or the deadline passes.
+ *
+ * `undefined` means "not yet" and nothing else — `false`, `0` and `''` are all
+ * answers, because a probe asking whether something happened reports `false`
+ * when it did not. Answering `undefined` at the deadline rather than throwing
+ * leaves the error to the caller, who is the only one who knows what was being
+ * waited for.
+ *
+ * A step that polls its target — a delivery reaching a terminal status, a run
+ * finishing — reaches for this rather than writing the deadline loop again.
+ */
+export const pollUntil = async <T>(
+  attempt: () => Promise<T | undefined> | T | undefined,
+  { timeoutMs = 15_000, intervalMs = 250 }: PollOptions = {}
+): Promise<T | undefined> => {
+  const deadline = Date.now() + timeoutMs
+  for (;;) {
+    const answer = await attempt()
+    if (answer !== undefined) {
+      return answer
+    }
+    if (Date.now() >= deadline) {
+      return undefined
+    }
+    await new Promise((done) => setTimeout(done, intervalMs))
+  }
+}

package/src/wirings/workflow/scenario-prose.test.ts

@@ -0,0 +1,152 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { composeStepProse, renderStepTemplate } from './scenario-prose.js'
+
+describe('renderStepTemplate', () => {
+  test('substitutes the step input into its placeholders', () => {
+    assert.equal(
+      renderStepTemplate('sees {packageName}', {
+        packageName: '@pikku/addon-stripe',
+      }),
+      'sees @pikku/addon-stripe'
+    )
+  })
+
+  test('renders numbers and booleans as words rather than JSON', () => {
+    assert.equal(
+      renderStepTemplate('sees at least {atLeast} addons, listed {listed}', {
+        atLeast: 10,
+        listed: true,
+      }),
+      'sees at least 10 addons, listed true'
+    )
+  })
+
+  test('an absent optional value leaves no gap in the sentence', () => {
+    assert.equal(
+      renderStepTemplate('sees {packageName} {state}', {
+        packageName: '@pikku/addon-stripe',
+      }),
+      'sees @pikku/addon-stripe'
+    )
+  })
+
+  test('a placeholder repeated in the template is substituted each time', () => {
+    assert.equal(
+      renderStepTemplate('searches {query} and sees {query}', {
+        query: 'stripe',
+      }),
+      'searches stripe and sees stripe'
+    )
+  })
+
+  test('a non-primitive value is serialised compactly', () => {
+    assert.equal(
+      renderStepTemplate('sends {payload}', { payload: { a: 1 } }),
+      'sends {"a":1}'
+    )
+  })
+
+  test('no recorded input leaves the template legible rather than half-rendered', () => {
+    assert.equal(renderStepTemplate('sees {packageName}', undefined), 'sees')
+  })
+})
+
+describe('composeStepProse', () => {
+  test('renders a template against the step input in place of the description', () => {
+    assert.equal(
+      composeStepProse({
+        phase: 'then',
+        description: 'sees an addon in the gallery',
+        template: 'sees {packageName}',
+        input: { packageName: '@pikku/addon-todos' },
+        actor: 'admin',
+      }),
+      'Then the admin sees @pikku/addon-todos'
+    )
+  })
+
+  test('falls back to the description when the step declares no template', () => {
+    assert.equal(
+      composeStepProse({
+        phase: 'then',
+        description: 'sees an addon in the gallery',
+        input: { packageName: '@pikku/addon-todos' },
+        actor: 'admin',
+      }),
+      'Then the admin sees an addon in the gallery'
+    )
+  })
+})
+
+describe('composeStepProse basics', () => {
+  test('renders the gherkin keyword, the actor and the description', () => {
+    assert.equal(
+      composeStepProse({
+        phase: 'given',
+        description: 'buys an apple',
+        actor: 'shopper',
+      }),
+      'Given the shopper buys an apple'
+    )
+    assert.equal(
+      composeStepProse({
+        phase: 'then',
+        description: 'sees a receipt',
+        actor: 'shopper',
+      }),
+      'Then the shopper sees a receipt'
+    )
+  })
+
+  test('an actorless step reads as a plain sentence', () => {
+    assert.equal(
+      composeStepProse({
+        phase: 'given',
+        description: 'the app data is reset',
+      }),
+      'Given the app data is reset'
+    )
+  })
+
+  test('the neutral `step` phase adds no keyword', () => {
+    assert.equal(
+      composeStepProse({
+        phase: 'step',
+        description: 'refreshes the dashboard',
+        actor: 'admin',
+      }),
+      'the admin refreshes the dashboard'
+    )
+  })
+
+  test('a keyword width lines the sentences up under each other', () => {
+    const rendered = (
+      [
+        { phase: 'given', description: 'buys an apple' },
+        { phase: 'when', description: 'checks out' },
+        { phase: 'then', description: 'sees a receipt' },
+        { phase: 'step', description: 'waits' },
+      ] as const
+    ).map((step) =>
+      composeStepProse({ ...step, actor: 'shopper', keywordWidth: 5 })
+    )
+
+    assert.deepEqual(rendered, [
+      'Given the shopper buys an apple',
+      'When  the shopper checks out',
+      'Then  the shopper sees a receipt',
+      '      the shopper waits',
+    ])
+    const columns = new Set(rendered.map((line) => line.indexOf('the shopper')))
+    assert.equal(columns.size, 1, 'every sentence starts in the same column')
+  })
+
+  test('prose degrades to just the description when nothing else is known', () => {
+    assert.equal(
+      composeStepProse({ phase: 'step', description: 'does the thing' }),
+      'does the thing'
+    )
+  })
+})