@pikku/core 0.12.69 → 0.12.71

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'
+    )
+  })
+})

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

@@ -0,0 +1,79 @@
+import type { ScenarioStepPhase } from './scenario-step.types.js'
+
+/**
+ * Renders the English sentence a reporter shows for a scenario step.
+ *
+ * This is the inversion of cucumber: rather than parsing English into a call,
+ * we render English out of a typed call, so the readable report survives
+ * without a regex registry paying for it.
+ *
+ * Lives in core so the CLI reporter and the console render identically.
+ */
+/**
+ * Fill a step's `template` from the input that step was actually called with,
+ * so the reported sentence names the values under test — "sees @pikku/addon-todos"
+ * rather than "sees an addon in the gallery" repeated three times.
+ *
+ * A placeholder with no recorded value renders as nothing and the surrounding
+ * whitespace collapses, so an optional input that was omitted reads as a shorter
+ * sentence rather than a literal `{state}` leaking into the report.
+ */
+export const renderStepTemplate = (
+  template: string,
+  input: unknown
+): string => {
+  const values =
+    input && typeof input === 'object' ? (input as Record<string, unknown>) : {}
+  return template
+    .replace(/\{(\w+)\}/g, (_match, key: string) => formatValue(values[key]))
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+
+const formatValue = (value: unknown): string => {
+  if (value === undefined || value === null) {
+    return ''
+  }
+  if (typeof value === 'object') {
+    return JSON.stringify(value)
+  }
+  return String(value)
+}
+
+export const composeStepProse = ({
+  phase,
+  description,
+  template,
+  input,
+  actor,
+  keywordWidth,
+}: {
+  phase: ScenarioStepPhase
+  description: string
+  /**
+   * The prose this step renders, with `{placeholders}` filled from `input`.
+   * Unlike `description`, which documents what the step does, this is what a
+   * reader of the report sees. Falls back to `description` when absent.
+   */
+  template?: string
+  /** The input this step was called with, as recorded on the run. */
+  input?: unknown
+  actor?: string
+  /**
+   * Pad the keyword to this width so a ladder of steps lines its sentences up
+   * under each other. Omit for inline prose.
+   */
+  keywordWidth?: number
+}): string => {
+  const keyword = phase === 'step' ? '' : capitalise(phase)
+  const subject = actor ? `the ${actor}` : ''
+  const rendered = template ? renderStepTemplate(template, input) : description
+  const sentence = [subject, rendered].filter(Boolean).join(' ')
+  if (keywordWidth === undefined) {
+    return [keyword, sentence].filter(Boolean).join(' ')
+  }
+  return `${keyword.padEnd(keywordWidth)} ${sentence}`
+}
+
+const capitalise = (value: string) =>
+  value.charAt(0).toUpperCase() + value.slice(1)

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

@@ -0,0 +1,155 @@
+import { describe, test, beforeEach } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { InMemoryWorkflowService } from '../../services/in-memory-workflow-service.js'
+import {
+  PikkuScenarioService,
+  createScenarioRunner,
+} from './pikku-scenario-service.js'
+import { pikkuState, resetPikkuState } from '../../pikku-state.js'
+
+const noopLogger = { error() {}, info() {}, warn() {}, debug() {} }
+
+/**
+ * Members that only a scenario run reaches. None of them may live on the class
+ * a production app instantiates: a bundler removes unused *modules*, never
+ * unused class members, so anything declared here ships in every server built
+ * on Pikku whether or not the app has a single scenario.
+ */
+const SCENARIO_MEMBERS = [
+  'scenarioStep',
+  'runScenarioHook',
+  'resolveScenarioActors',
+  'setScenarioBrowserProvider',
+  'getScenarioBrowserProvider',
+  'setScenarioEnvironment',
+  'getScenarioEnvironment',
+]
+
+/** Wire members declared by `PikkuScenarioWire` and absent from `PikkuWorkflowWire`. */
+const SCENARIO_WIRE_MEMBERS = [
+  'step',
+  'given',
+  'when',
+  'then',
+  'expectEventually',
+  'expectError',
+  'expectService',
+  'runScheduledTask',
+]
+
+const setup = async (ws: InMemoryWorkflowService) => {
+  pikkuState(null, 'package', 'singletonServices', {
+    logger: noopLogger,
+  } as any)
+  const runId = await ws.createRun('surfaceTest', {}, true, 'hash', {
+    type: 'test',
+  } as any)
+  ws.registerInlineRun(runId)
+  return runId
+}
+
+describe('the production workflow service carries no scenario surface', () => {
+  beforeEach(() => resetPikkuState())
+
+  test('no scenario method is declared on the workflow service prototype chain', () => {
+    const ws = new InMemoryWorkflowService()
+    for (const member of SCENARIO_MEMBERS) {
+      assert.equal(
+        typeof (ws as any)[member],
+        'undefined',
+        `'${member}' ships in every production bundle while it is a member of PikkuWorkflowService`
+      )
+    }
+  })
+
+  test('the workflow wire exposes only workflow members', async () => {
+    const ws = new InMemoryWorkflowService()
+    const runId = await setup(ws)
+    const wire = ws.createWorkflowWire('surfaceTest', runId, {}) as any
+
+    for (const member of SCENARIO_WIRE_MEMBERS) {
+      assert.equal(
+        typeof wire[member],
+        'undefined',
+        `wire.${member} is a scenario affordance and must not be built for a production workflow run`
+      )
+    }
+    for (const member of ['do', 'sleep', 'suspend', 'approval', 'getRun']) {
+      assert.equal(
+        typeof wire[member],
+        'function',
+        `wire.${member} is a workflow member and must survive`
+      )
+    }
+  })
+
+  test('a service with no extension installed runs a plain workflow untouched', async () => {
+    const ws = new InMemoryWorkflowService()
+    assert.equal(ws.getRunExtension(), undefined)
+    const runId = await setup(ws)
+    const wire = ws.createWorkflowWire('surfaceTest', runId, {}) as any
+    assert.equal(typeof wire.do, 'function')
+  })
+
+  test('the actor client is not reachable from the workflow service module graph', async () => {
+    const { readFileSync } = await import('node:fs')
+    const source = readFileSync(
+      new URL('./pikku-workflow-service.ts', import.meta.url),
+      'utf8'
+    )
+    assert.ok(
+      !source.includes('http-scenario-actors'),
+      'PikkuWorkflowService must not reference the HTTP actor client — it pulls the AI persona loop into every bundle'
+    )
+  })
+})
+
+describe('PikkuScenarioService carries the scenario surface', () => {
+  beforeEach(() => resetPikkuState())
+
+  test('every scenario method is declared on the scenario service', () => {
+    const { scenarioService } = createScenarioRunner()
+    for (const member of SCENARIO_MEMBERS) {
+      assert.equal(
+        typeof (scenarioService as any)[member],
+        'function',
+        `PikkuScenarioService is missing '${member}'`
+      )
+    }
+  })
+
+  test('the wire it decorates carries both the workflow and the scenario members', async () => {
+    const { workflowService: ws } = createScenarioRunner()
+    const runId = await setup(ws)
+    const wire = ws.createWorkflowWire('surfaceTest', runId, {}) as any
+
+    for (const member of [
+      ...SCENARIO_WIRE_MEMBERS,
+      'do',
+      'sleep',
+      'approval',
+    ]) {
+      assert.equal(
+        typeof wire[member],
+        'function',
+        `PikkuScenarioService's wire is missing ${member}`
+      )
+    }
+  })
+
+  test('it is not a workflow service, so it cannot be registered as one by mistake', () => {
+    const { scenarioService } = createScenarioRunner()
+    assert.ok(!(scenarioService instanceof InMemoryWorkflowService))
+    assert.equal(
+      typeof (scenarioService as any).startWorkflow,
+      'undefined',
+      'the scenario capability is layered onto a run, it does not own one'
+    )
+  })
+
+  test('the runner installs it as the workflow service extension', () => {
+    const { workflowService, scenarioService } = createScenarioRunner()
+    assert.equal(workflowService.getRunExtension(), scenarioService)
+  })
+})

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

@@ -0,0 +1,43 @@
+import type {
+  PikkuScenarioStepWire,
+  ScenarioEnvironment,
+} from './scenario-step.types.js'
+
+/**
+ * The actor this step was called with, or a loud error naming the step.
+ *
+ * A step that talks to the target app needs an identity, but `actor` is
+ * optional on the wire because a pure assertion step needs none. This is the
+ * one place that narrowing happens, so every step file stops writing its own
+ * `actorOf(...)` guard.
+ */
+export const requireActor = <TActor>(
+  scenarioStep: PikkuScenarioStepWire<TActor> | undefined
+): TActor => {
+  const actor = scenarioStep?.actor
+  if (!actor) {
+    throw new Error(
+      `[scenario] step '${scenarioStep?.name ?? 'unknown'}' was called without an actor. ` +
+        `Pass { actor: actors.<name> } so it runs as that persona.`
+    )
+  }
+  return actor
+}
+
+/**
+ * The environment this run targets, or a loud error naming the step. A run
+ * started outside `pikku scenario run` only carries one when the server has
+ * `API_URL` configured.
+ */
+export const requireScenarioEnv = (
+  scenarioStep: PikkuScenarioStepWire<unknown> | undefined
+): ScenarioEnvironment => {
+  const env = scenarioStep?.env
+  if (!env) {
+    throw new Error(
+      `[scenario] step '${scenarioStep?.name ?? 'unknown'}' needs the target environment, but this run carries none. ` +
+        `Run it through 'pikku scenario run <environment>' with scenarios.environments.<environment> declared in pikku.config.json.`
+    )
+  }
+  return env
+}