@pikku/core 0.12.107 → 0.12.112

package/src/wirings/workflow/scenario-step.types.ts

@@ -1,262 +0,0 @@
-import type { ScenarioArtifact } from './scenario-run.types.js'
-
-/**
- * Scenario steps: named, typed units of scenario behaviour.
- *
- * A step's body is an ordinary pikku function, so it may drive a browser, call
- * an RPC as its actor, or run a workflow. `given` and `when` differ only in the
- * prose the reporter renders; `then` also changes what runs, because its
- * bindings are witnesses — every declared surface is observed and the
- * observations must agree. See {@link ScenarioSurfaceResolution}.
- */
-
-/**
- * Which Gherkin-style keyword the reporter prefixes this step with.
- *
- * Every step takes one. A scenario is read by people deciding whether it
- * describes the behaviour they wanted, and a step that says only what it does
- * without saying whether it is setup, action or claim is the one nobody can
- * check — which is also why PKU680 can tell a scenario that never asserts.
- */
-export type ScenarioStepPhase = 'given' | 'when' | 'then'
-
-/**
- * Who acts in a step.
- *
- * `persona` is a person driving the system through one of its surfaces — the
- * ordinary `pikkuScenarioStep`. `platform` is the app acting on itself ("the
- * platform has expired the trial"), and `addon` is a third-party system acting
- * on it ("Stripe's webhook arrives"), contributed by the addon that wraps that
- * service.
- *
- * The three are separate declarations rather than a field on one, so the
- * inspector verifies a step's kind by which function was called rather than by
- * trusting a string literal — and so an addon package exports only addon steps,
- * which is checkable.
- */
-export type ScenarioStepKind = 'persona' | 'platform' | 'addon'
-
-/**
- * How an actor drives the system for one step.
- *
- * A step declares one implementation per surface it supports, and the runner
- * picks between them — so the same ladder can run through a real browser, over
- * the websocket, or entirely server-side.
- *
- * `default` is the floor: it is what every other surface falls back to, so it
- * can never itself fall back.
- */
-export type ScenarioSurface = 'browser' | 'cli' | 'default'
-
-export const SCENARIO_SURFACES: readonly ScenarioSurface[] = [
-  'browser',
-  'cli',
-  'default',
-]
-
-/**
- * How a step's declared surfaces resolve for one run.
- *
- * `given`/`when` bindings are **alternatives** — clicking Buy and calling
- * `createOrder` are two ways to cause one effect, so exactly one runs.
- *
- * `then` bindings are **witnesses** — "the order row says paid" and "the
- * confirmation panel says paid" are different claims that share a name, and the
- * gap between them is the bug nobody catches. So every declared witness runs and
- * they must agree.
- */
-export type ScenarioSurfaceResolution =
-  | {
-      kind: 'action'
-      surface: ScenarioSurface
-      /** The run asked for a surface this step does not implement. */
-      fellBack: boolean
-    }
-  | {
-      kind: 'witness'
-      /**
-       * Every witness to run, surface first. Empty means the assertion has no
-       * binding this run can execute at all — nothing would check anything, so
-       * the step fails rather than reporting a pass it never earned.
-       */
-      surfaces: ScenarioSurface[]
-      /**
-       * Something checked the assertion, but not on the surface its prose
-       * claims — so nobody looked at the UI. Reported as its own state and
-       * counted against coverage: not being in the UI *is* the finding.
-       *
-       * Disjoint from an empty `surfaces`; an assertion that ran nowhere is a
-       * failure, not a coverage statistic.
-       */
-      unwitnessed: boolean
-    }
-
-/**
- * Options accepted by `scenario.given/when/then`.
- *
- * Note the retry default differs from an ordinary workflow step: retrying a
- * failed assertion is the wrong behaviour for a test primitive, so steps
- * default to no retries.
- */
-export interface ScenarioStepOptions {
-  /**
-   * The actor this step runs as. Required for a step that declares `actor: true`
-   * or a `browser` binding; the runner refuses to dispatch one without it.
-   */
-  actor?: unknown
-  /** Overrides the step's own `description` for this call site only. */
-  description?: string
-  /** Defaults to 0 for steps — a failed assertion must not be retried. */
-  retries?: number
-  retryDelay?: number | string
-}
-
-/**
- * The environment a scenario run targets, as declared in pikku.config.json
- * under `environments`.
- */
-export interface ScenarioEnvironment {
-  /** Base API URL of the target app, INCLUDING the HTTP prefix. */
-  apiUrl: string
-  /** Base URL of the app's UI, for environments with browser steps. */
-  appUrl?: string
-}
-
-/**
- * The `scenarioStep` wire, present on every scenario step invocation.
- *
- * The persona a step runs as is not here: it arrives as `wire.actor`, injected
- * by the runner and typed as present exactly on the bindings that declared they
- * need one. Keeping it off this interface is what makes that possible — a wire
- * member can be required per binding, a property of one cannot.
- */
-export interface PikkuScenarioStepWire {
-  /** Registered step name (also its pikkuFuncId) */
-  name: string
-  /** Durable key within the run; may carry an `#ordinal` suffix when repeated */
-  stepName: string
-  runId: string
-  phase: ScenarioStepPhase
-  /**
-   * Which of the step's bindings is currently executing. A `then` step runs once
-   * per witness, so its body sees this change between invocations.
-   */
-  surface: ScenarioSurface
-  /**
-   * The environment this run targets. A step runs in the CLI process, where
-   * there is no `variables` service — this is how a raw-HTTP step learns the
-   * target's URL without reaching for `process.env`.
-   */
-  env?: ScenarioEnvironment
-}
-
-/**
- * How a browser step names an element.
- *
- * A `data-testid` on its own is rarely enough to name exactly one: `where`
- * matches the element's own data attributes (so a step asserts a status
- * without reading translated copy back to the app), `prefix` matches a family
- * of ids, `containing` picks the match holding a piece of text, and `within`
- * scopes the lookup to one row or section.
- *
- * Declared here so a step's input type is structural; the driver
- * (`@pikku/playwright`) is what resolves it against a real page.
- */
-export interface TestIdSelector {
-  testId: string
-  /** Match every test id beginning with `testId`, e.g. every `flow-card-*`. */
-  prefix?: boolean
-  /** Data attributes the element must also carry, e.g. `{ 'data-open': 'true' }`. */
-  where?: Record<string, string>
-  /** Narrow to the one match holding this text. */
-  containing?: string
-  /** Scope the lookup to one enclosing element, e.g. the row for one user. */
-  within?: TestIdSelector
-}
-
-/**
- * Structural browser handle, present only when the runner provisioned a
- * browser for this step (a `browser` binding on the step config).
- *
- * `@pikku/core` deliberately never imports playwright — it must stay
- * dependency-free for edge runtimes. `@pikku/playwright` augments this
- * interface via `declare module`, so `wire.browser.page` is a fully typed
- * Playwright `Page` in a project that installs it.
- */
-export interface PikkuBrowserWire {
-  /** The actor whose browser context this is */
-  readonly actor: string
-  goto(url: string): Promise<void>
-  screenshot(name?: string): Promise<Uint8Array>
-}
-
-/**
- * What one actor's window looked like at the moment a scenario failed.
- *
- * A browser step fails with a selector timeout that says nothing about *why*
- * the page never rendered. The answer is almost always in the page's own
- * errors, which the driver has been collecting all along.
- */
-export interface ScenarioBrowserFailure {
-  /** The actor whose window this is. */
-  actor: string
-  /** Where the window was pointed, when the driver can still report it. */
-  url?: string
-  /** Path the screenshot was written to; absent when none could be taken. */
-  screenshot?: string
-  consoleErrors: string[]
-  pageErrors: string[]
-  failedRequests: string[]
-  apiErrors: string[]
-}
-
-/**
- * Supplied by `@pikku/playwright` (or any other driver) and consumed by the
- * scenario runner. Declared here so the CLI depends only on core.
- *
- * `reset` and `captureFailure` are optional so a driver written against an
- * earlier version keeps compiling; the runner treats a driver without them as
- * one that simply offers no isolation and no diagnostics.
- */
-export interface ScenarioBrowserProvider {
-  /** Resolve — creating on first use — the browser session for an actor. */
-  sessionFor(actorName: string): Promise<PikkuBrowserWire>
-  /**
-   * Discard every actor's per-scenario state — cookies, storage, open pages —
-   * while keeping the browser itself. Called between scenarios, so one
-   * scenario cannot leave the next signed in as somebody else.
-   */
-  reset?(): Promise<void>
-  /**
-   * Name the scenario about to run, so anything it captures is filed under it.
-   *
-   * Called before each scenario. A provider that is never told has to fall
-   * back to one shared label, which puts every run's artifacts in a single
-   * folder — findable only by timestamp.
-   */
-  beginScenario?(scenario: string): void
-  /**
-   * Report how the scenario that just ran finished.
-   *
-   * Called after each scenario, and separate from `reset()` because artifacts
-   * that only exist once a window closes — a video — are produced by the NEXT
-   * scenario's reset, long after the outcome that decides whether to keep them.
-   */
-  endScenario?(outcome: 'passed' | 'failed'): void
-  /**
-   * Snapshot every open window for a failed scenario. `label` identifies the
-   * scenario in artifact filenames. Never throws: a failure to capture must
-   * not replace the failure being captured.
-   */
-  captureFailure?(label: string): Promise<ScenarioBrowserFailure[]>
-  /**
-   * Everything the run filed, each entry naming the scenario it belongs to.
-   *
-   * Reported by the driver rather than discovered by scanning the directory:
-   * only the driver knows which window produced a file and under what caption,
-   * and a video's final name is not settled until the run closes. Read after
-   * `close()`, which is the first moment the answer is complete.
-   */
-  artifacts?(): ScenarioArtifact[]
-  close(): Promise<void>
-}

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

@@ -1,146 +0,0 @@
-import { describe, test } from 'node:test'
-import assert from 'node:assert/strict'
-import { resolveScenarioSurfaces, witnessesAgree } from './scenario-surface.js'
-import type { ScenarioSurface } from './scenario-step.types.js'
-
-const ALL: ScenarioSurface[] = ['browser', 'cli', 'default']
-
-describe('action steps pick exactly one binding', () => {
-  test('runs the binding the run asked for', () => {
-    assert.deepEqual(resolveScenarioSurfaces('when', ALL, 'browser'), {
-      kind: 'action',
-      surface: 'browser',
-      fellBack: false,
-    })
-  })
-
-  test('falls back to default and says so when the surface is not implemented', () => {
-    assert.deepEqual(resolveScenarioSurfaces('when', ['default'], 'browser'), {
-      kind: 'action',
-      surface: 'default',
-      fellBack: true,
-    })
-  })
-
-  test('given resolves like when, not like then', () => {
-    assert.deepEqual(resolveScenarioSurfaces('given', ALL, 'cli'), {
-      kind: 'action',
-      surface: 'cli',
-      fellBack: false,
-    })
-  })
-
-  test('a default run never counts as a fallback', () => {
-    assert.deepEqual(resolveScenarioSurfaces('when', ['default'], 'default'), {
-      kind: 'action',
-      surface: 'default',
-      fellBack: false,
-    })
-  })
-})
-
-describe('then steps run every witness', () => {
-  test('a browser run checks the page AND the system of record', () => {
-    assert.deepEqual(
-      resolveScenarioSurfaces('then', ['browser', 'default'], 'browser'),
-      { kind: 'witness', surfaces: ['browser', 'default'], unwitnessed: false }
-    )
-  })
-
-  test('the surface witness comes first, so its failure is the one reported', () => {
-    const resolution = resolveScenarioSurfaces(
-      'then',
-      ['default', 'browser'],
-      'browser'
-    )
-    assert.equal(resolution.kind, 'witness')
-    assert.deepEqual(
-      resolution.kind === 'witness' ? resolution.surfaces[0] : null,
-      'browser'
-    )
-  })
-
-  test('a default run is unchanged — one witness, no extra cost', () => {
-    assert.deepEqual(
-      resolveScenarioSurfaces('then', ['browser', 'default'], 'default'),
-      { kind: 'witness', surfaces: ['default'], unwitnessed: false }
-    )
-  })
-
-  test('no witness for the run surface is flagged rather than excused', () => {
-    assert.deepEqual(resolveScenarioSurfaces('then', ['default'], 'browser'), {
-      kind: 'witness',
-      surfaces: ['default'],
-      unwitnessed: true,
-    })
-  })
-
-  test('a browser-only assertion has nothing to run on a default run', () => {
-    // No witness at all is not a coverage statistic — nothing checked anything,
-    // so `unwitnessed` stays false and the caller is expected to fail the step.
-    assert.deepEqual(resolveScenarioSurfaces('then', ['browser'], 'default'), {
-      kind: 'witness',
-      surfaces: [],
-      unwitnessed: false,
-    })
-  })
-
-  test('an assertion that runs nowhere is not counted as merely unwitnessed', () => {
-    assert.deepEqual(resolveScenarioSurfaces('then', ['browser'], 'cli'), {
-      kind: 'witness',
-      surfaces: [],
-      unwitnessed: false,
-    })
-  })
-
-  test('unwitnessed means checked somewhere else, never checked nowhere', () => {
-    const ranElsewhere = resolveScenarioSurfaces('then', ['default'], 'cli')
-    assert.equal(ranElsewhere.kind, 'witness')
-    assert.ok(
-      ranElsewhere.kind === 'witness' && ranElsewhere.surfaces.length > 0,
-      'the two states are disjoint: unwitnessed always has something that ran'
-    )
-    assert.equal(
-      ranElsewhere.kind === 'witness' && ranElsewhere.unwitnessed,
-      true
-    )
-  })
-})
-
-describe('witness agreement', () => {
-  test('key order does not make two observations disagree', () => {
-    assert.equal(
-      witnessesAgree(
-        { status: 'paid', total: 500 },
-        { total: 500, status: 'paid' }
-      ),
-      true
-    )
-  })
-
-  test('a page showing something else is a disagreement', () => {
-    assert.equal(
-      witnessesAgree({ status: 'paid' }, { status: 'pending' }),
-      false
-    )
-  })
-
-  test('a witness that asserted by throwing is not compared', () => {
-    assert.equal(witnessesAgree(undefined, { status: 'paid' }), true)
-    assert.equal(witnessesAgree({ status: 'paid' }, undefined), true)
-  })
-
-  test('nested observations compare structurally', () => {
-    assert.equal(
-      witnessesAgree(
-        { order: { items: [{ sku: 'a' }, { sku: 'b' }] } },
-        { order: { items: [{ sku: 'a' }, { sku: 'b' }] } }
-      ),
-      true
-    )
-    assert.equal(
-      witnessesAgree({ items: ['a', 'b'] }, { items: ['b', 'a'] }),
-      false
-    )
-  })
-})

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

@@ -1,71 +0,0 @@
-import type {
-  ScenarioStepPhase,
-  ScenarioSurface,
-  ScenarioSurfaceResolution,
-} from './scenario-step.types.js'
-
-/**
- * Resolve which of a step's declared bindings run, for one step, in one run.
- *
- * The asymmetry between phases is the whole point — see
- * {@link ScenarioSurfaceResolution}.
- */
-export const resolveScenarioSurfaces = (
-  phase: ScenarioStepPhase,
-  declared: readonly ScenarioSurface[],
-  runSurface: ScenarioSurface
-): ScenarioSurfaceResolution => {
-  const has = (surface: ScenarioSurface) => declared.includes(surface)
-
-  if (phase !== 'then') {
-    if (has(runSurface)) {
-      return { kind: 'action', surface: runSurface, fellBack: false }
-    }
-    return { kind: 'action', surface: 'default', fellBack: true }
-  }
-
-  const surfaces: ScenarioSurface[] = []
-  if (runSurface !== 'default' && has(runSurface)) {
-    surfaces.push(runSurface)
-  }
-  if (has('default')) {
-    surfaces.push('default')
-  }
-  return {
-    kind: 'witness',
-    surfaces,
-    // Only meaningful once something ran: an assertion checked server-side
-    // under `--run browser` is a coverage gap, but one checked nowhere at all
-    // is a step that did not happen, which the caller fails rather than counts.
-    unwitnessed:
-      surfaces.length > 0 && runSurface !== 'default' && !has(runSurface),
-  }
-}
-
-/**
- * Structural comparison of two witnesses' observations.
- *
- * A witness that returns `undefined` asserted by throwing rather than by
- * reporting what it saw, so it is not compared — that keeps assertion-style
- * steps working without forcing every one of them to return a value.
- */
-export const witnessesAgree = (a: unknown, b: unknown): boolean => {
-  if (a === undefined || b === undefined) {
-    return true
-  }
-  return stableStringify(a) === stableStringify(b)
-}
-
-const stableStringify = (value: unknown): string => {
-  if (value === null || typeof value !== 'object') {
-    return JSON.stringify(value) ?? 'undefined'
-  }
-  if (Array.isArray(value)) {
-    return `[${value.map(stableStringify).join(',')}]`
-  }
-  const entries = Object.entries(value as Record<string, unknown>)
-    .filter(([, v]) => v !== undefined)
-    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
-    .map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`)
-  return `{${entries.join(',')}}`
-}

package/src/wirings/workflow/scenario.types.ts

@@ -1,63 +0,0 @@
-import type {
-  CorePikkuFunctionConfig,
-  CorePikkuFunctionHook,
-} from '../../function/functions.types.js'
-
-export type {
-  ScenarioStepInvocation,
-  ScenarioStepMeta,
-  PikkuScenarioWire,
-} from './dsl/workflow-dsl.types.js'
-
-export type {
-  ScenarioStepPhase,
-  ScenarioStepKind,
-  ScenarioStepOptions,
-  PikkuScenarioStepWire,
-  ScenarioEnvironment,
-  ScenarioSurface,
-  ScenarioSurfaceResolution,
-  PikkuBrowserWire,
-  TestIdSelector,
-  ScenarioBrowserProvider,
-  ScenarioBrowserFailure,
-} from './scenario-step.types.js'
-
-export type CoreFeatureScenario =
-  | CorePikkuFunctionConfig<any, any, any>
-  | { scenario: CorePikkuFunctionConfig<any, any, any>; data: unknown }
-
-export type CoreFeature = {
-  name: string
-  description?: string
-  tags?: string[]
-  scenarios: readonly CoreFeatureScenario[]
-  before?: CorePikkuFunctionHook
-  after?: CorePikkuFunctionHook
-}
-
-export type FeatureMetaEntry = {
-  scenario: string
-  data?: unknown
-}
-
-export type FeatureMeta = {
-  id: string
-  name: string
-  description?: string
-  tags: string[]
-  entries: FeatureMetaEntry[]
-  unresolvedEntries: number
-  hasBefore: boolean
-  hasAfter: boolean
-}
-
-export type FeaturesMeta = Record<string, FeatureMeta>
-
-export type FeaturePlanEntry = {
-  featureId: string
-  featureName: string
-  scenarioName: string
-  data?: unknown
-  tags: string[]
-}

package/src/wirings/workflow/workflow-approval-audit.ts

@@ -1,47 +0,0 @@
-import { getSingletonServices } from '../../pikku-state.js'
-import type { ApprovalAuditEvent } from './workflow-approval.js'
-
-/** The audit type an answer to an approval gate is recorded under. */
-export const APPROVAL_AUDIT_TYPE = 'workflow.approval.decided'
-
-/**
- * Record an answer to an approval gate where it outlives the run.
- *
- * The step result carries the settled decision, but it is deleted with the run
- * — `deleteRun` cascades to steps and to history — and a refused attempt never
- * reaches a step at all. An approval is asked for precisely so it can be
- * answered for afterwards, so the answer also goes to the audit sink, which
- * holds no foreign key to the run.
- *
- * A project with no sink wired records nothing, and a sink that fails is logged
- * rather than thrown: the trail must not be the reason a decision is lost.
- */
-export const auditApprovalDecision = async (
-  event: ApprovalAuditEvent
-): Promise<void> => {
-  const services = getSingletonServices()
-  if (!services?.audit) {
-    return
-  }
-  try {
-    await services.audit.audit({
-      type: APPROVAL_AUDIT_TYPE,
-      source: 'explicit',
-      outcome: event.outcome,
-      occurredAt: new Date().toISOString(),
-      wireType: 'workflow',
-      userIdentity: { pikkuUserId: event.decidedBy?.userId },
-      metadata: {
-        runId: event.runId,
-        reason: event.reason,
-        scopes: event.decidedBy?.scopes,
-        refusal: event.refusal,
-      },
-    })
-  } catch (error) {
-    services.logger?.warn(
-      `Failed to audit the decision on approval '${event.reason}' for run ${event.runId}`,
-      error
-    )
-  }
-}