@pikku/core 0.12.107 → 0.12.112

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

@@ -1,275 +0,0 @@
-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 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 admin sees an addon in the gallery'
-    )
-  })
-})
-
-describe('composeStepProse with an actor role', () => {
-  test('the role renders as an apposition after the actor', () => {
-    assert.equal(
-      composeStepProse({
-        phase: 'given',
-        description: 'signs in',
-        actor: 'yasser',
-        actorRole: 'founder',
-      }),
-      'Given yasser (the founder) signs in'
-    )
-  })
-
-  test('no role renders exactly as it did before', () => {
-    assert.equal(
-      composeStepProse({
-        phase: 'given',
-        description: 'signs in',
-        actor: 'yasser',
-      }),
-      'Given yasser signs in'
-    )
-  })
-
-  test('a role without an actor has nothing to qualify, so it is dropped', () => {
-    assert.equal(
-      composeStepProse({
-        phase: 'then',
-        description: 'the receipt totals 4.50',
-        actorRole: 'founder',
-      }),
-      'Then the receipt totals 4.50'
-    )
-  })
-
-  test('the role sits inside the padded sentence, not the keyword column', () => {
-    assert.equal(
-      composeStepProse({
-        phase: 'when',
-        description: 'opens /app',
-        actor: 'nadia',
-        actorRole: 'head of ops',
-        keywordWidth: 5,
-      }),
-      'When  nadia (the head of ops) opens /app'
-    )
-  })
-})
-
-describe('composeStepProse continuations', () => {
-  test('a repeated phase reads as And', () => {
-    assert.equal(
-      composeStepProse({
-        phase: 'given',
-        description: 'is invited',
-        actor: 'nadia',
-        continuesPhase: true,
-      }),
-      'And nadia is invited'
-    )
-  })
-
-  test('the same actor continuing drops the repeated subject', () => {
-    assert.equal(
-      composeStepProse({
-        phase: 'when',
-        description: 'sees the audit log',
-        actor: 'yasser',
-        continuesPhase: true,
-        continuesActor: true,
-      }),
-      'And sees the audit log'
-    )
-  })
-
-  test('a new actor keeps their name even under And', () => {
-    assert.equal(
-      composeStepProse({
-        phase: 'given',
-        description: 'is invited',
-        actor: 'nadia',
-        continuesPhase: true,
-        continuesActor: false,
-      }),
-      'And nadia is invited'
-    )
-  })
-
-  test('the same actor across a phase change keeps the subject', () => {
-    assert.equal(
-      composeStepProse({
-        phase: 'when',
-        description: 'opens the dashboard',
-        actor: 'yasser',
-        continuesActor: true,
-      }),
-      'When yasser opens the dashboard'
-    )
-  })
-
-  test('an introduction is never dropped by a continuation', () => {
-    assert.equal(
-      composeStepProse({
-        phase: 'given',
-        description: 'is invited',
-        actor: 'nadia',
-        actorRole: 'reviewer',
-        continuesPhase: true,
-      }),
-      'And nadia (the reviewer) is invited'
-    )
-  })
-})
-
-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 shopper buys an apple'
-    )
-    assert.equal(
-      composeStepProse({
-        phase: 'then',
-        description: 'sees a receipt',
-        actor: 'shopper',
-      }),
-      'Then shopper sees a receipt'
-    )
-  })
-
-  test('a persona named after a person reads as that person', () => {
-    assert.equal(
-      composeStepProse({
-        phase: 'when',
-        description: 'opens /app',
-        actor: 'nadia',
-      }),
-      'When nadia opens /app'
-    )
-  })
-
-  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('every phase renders its keyword', () => {
-    assert.equal(
-      composeStepProse({
-        phase: 'when',
-        description: 'refreshes the dashboard',
-        actor: 'admin',
-      }),
-      'When 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' },
-      ] as const
-    ).map((step) =>
-      composeStepProse({ ...step, actor: 'shopper', keywordWidth: 5 })
-    )
-
-    assert.deepEqual(rendered, [
-      'Given shopper buys an apple',
-      'When  shopper checks out',
-      'Then  shopper sees a receipt',
-    ])
-    const columns = new Set(rendered.map((line) => line.indexOf('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: 'when', description: 'does the thing' }),
-      'When does the thing'
-    )
-  })
-})

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

@@ -1,86 +0,0 @@
-import type { ScenarioStepPhase } from './scenario-step.types.js'
-
-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,
-  actorRole,
-  continuesPhase,
-  continuesActor,
-  keywordWidth,
-}: {
-  phase: ScenarioStepPhase
-  description: string
-  template?: string
-  input?: unknown
-  actor?: string
-  /**
-   * What this actor is, rendered as an apposition after their key — "yasser
-   * (the founder)". Only pass it where the actor has not been named yet: an
-   * ordinary run repeats one actor for a dozen steps, and repeating the role
-   * with them turns the one piece of context into the noise around it.
-   */
-  actorRole?: string
-  /**
-   * This step repeats the phase of the one before it, so it reads as `And`
-   * rather than saying `Given` three times — the same thing Gherkin does.
-   */
-  continuesPhase?: boolean
-  /**
-   * The step before this one had the same actor. Combined with `continuesPhase`
-   * the subject is dropped, because English drops a repeated subject in a
-   * compound predicate: "yasser opens the dashboard / and sees the audit log".
-   *
-   * It takes both. Dropping the subject across a phase change gives "When opens
-   * the dashboard", and a pronoun instead of a name would give "they sees",
-   * since step templates are authored in the third person singular.
-   */
-  continuesActor?: boolean
-  keywordWidth?: number
-}): string => {
-  const keyword = capitalise(continuesPhase ? 'and' : phase)
-  // The actor key is the subject verbatim, with no article in front of it.
-  // "the ${actor}" only reads as English when the key happens to be a role
-  // noun — it turns a persona named after a person into "the nadia", which
-  // is the reporter quietly imposing a naming convention on the author.
-  const subject =
-    continuesPhase && continuesActor ? '' : composeSubject(actor, actorRole)
-  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 composeSubject = (actor?: string, actorRole?: string): string => {
-  if (!actor) return ''
-  return actorRole ? `${actor} (the ${actorRole})` : actor
-}
-
-const capitalise = (value: string) =>
-  value.charAt(0).toUpperCase() + value.slice(1)

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

@@ -1,193 +0,0 @@
-/**
- * What one `pikku scenario run` leaves behind.
- *
- * A run is history: the scenarios it selected, the sentences they were made of,
- * and the images and footage they produced. The sentences are snapshotted into
- * the record rather than looked up later, because a scenario is code and the
- * code moves — a run from last week describes a suite that no longer exists,
- * and re-deriving its ladder from today's source would quietly rewrite it.
- *
- * Everything here is plain serialisable data. That is what lets one record be
- * a JSON file on disk in OSS and a row in Postgres on a hosted project, read
- * back by the same console screen either way.
- */
-import type { ScenarioBrowserFailure } from './scenario-step.types.js'
-
-/** What a run filed, in the order it filed it. */
-export type ScenarioArtifactKind = 'screenshot' | 'failure' | 'video'
-
-/**
- * One image or recording a scenario produced.
- *
- * `path` is relative to the run's artifact root and always uses forward
- * slashes: it is a content key, not a filesystem path. Locally it resolves
- * under the run's directory; on a hosted project it is the object key in a
- * bucket, and the same record works unchanged.
- */
-export interface ScenarioArtifact {
-  /** The scenario label this belongs to, as the report names it. */
-  scenario: string
-  kind: ScenarioArtifactKind
-  path: string
-  /** Whose window it was — a two-actor scenario produces two of everything. */
-  actor?: string
-  /** The caption the scenario author took a screenshot under. */
-  name?: string
-}
-
-/** One step of a run, already joined to the prose that declared it. */
-export interface ScenarioStepRow {
-  sentence: string
-  /**
-   * The same sentence with the actor's role in it — "yasser (the founder)
-   * signs in". Set only on the step that first names each actor, and only
-   * when a persona declares a job title or a role, so a reader who wants the
-   * context picks this and one who wants the bare run picks `sentence`.
-   */
-  sentenceWithRole?: string
-  status: string
-  durationMs?: number
-  error?: string
-}
-
-/** Everything known about why one scenario failed. */
-export interface ScenarioFailureDetail {
-  /** The rendered sentence of the failing step; absent if no step failed. */
-  sentence?: string
-  message: string
-  stack?: string
-  /**
-   * True when the failure was a deliberate one (a PikkuError). Its message is
-   * the whole story, so the stack is noise.
-   */
-  expected?: boolean
-  browser?: ScenarioBrowserFailure[]
-}
-
-export interface ScenarioResult {
-  name: string
-  status: 'passed' | 'failed'
-  durationMs: number
-  output?: unknown
-  error?: string
-  steps?: ScenarioStepRow[]
-  failure?: ScenarioFailureDetail
-  /** The scenario registration this ran, which the label alone does not give. */
-  scenarioName?: string
-  /** The feature that grouped it, when one did. */
-  feature?: string
-  tags?: string[]
-  /** Images and footage this scenario produced, filed under the run. */
-  artifacts?: ScenarioArtifact[]
-}
-
-/** One scenario that was not run, and why. */
-export interface ScenarioSkip {
-  name: string
-  reason: string
-}
-
-export interface ScenarioRunReport {
-  environment: string
-  results: ScenarioResult[]
-  /**
-   * Scenarios not run at all, each carrying why. A skip is only useful if the
-   * reader can tell a browser scenario held back by `--no-browser` from one the
-   * project itself quarantined, so the reason travels with the name rather than
-   * being assumed by the formatter.
-   */
-  skipped: ScenarioSkip[]
-  /** Feature-level hook failures, which belong to no single scenario. */
-  hookFailures: string[]
-}
-
-export type ScenarioRunStatus = 'running' | 'passed' | 'failed'
-
-/**
- * A whole run, as it is stored and read back.
- *
- * `status` is `running` from the moment the run is created until it finishes,
- * so a console watching a run in progress can tell "still going" from "nothing
- * came back" — and a run killed halfway stays `running` forever, which is the
- * honest record of what happened to it.
- */
-export interface ScenarioRunRecord extends ScenarioRunReport {
-  runId: string
-  status: ScenarioRunStatus
-  /** The surface the run targeted: `default`, `browser`, … */
-  surface: string
-  startedAt: string
-  finishedAt?: string
-}
-
-/** Enough of a run to list it without loading its steps and stacks. */
-export interface ScenarioRunSummary {
-  runId: string
-  environment: string
-  surface: string
-  status: ScenarioRunStatus
-  startedAt: string
-  finishedAt?: string
-  durationMs?: number
-  passed: number
-  failed: number
-  skipped: number
-  /** Whether anything is there to watch, so a list can say so without a second read. */
-  artifacts: number
-}
-
-/**
- * Where runs are kept.
- *
- * Deliberately not the workflow service: a scenario run is a workflow run under
- * the hood, but its history has a different lifetime, a different audience, and
- * a different home — a JSON file beside the project locally, a project-scoped
- * table and an object store when hosted.
- *
- * Written progressively rather than at the end, so a suite that dies on its
- * fortieth scenario still leaves the thirty-nine behind.
- */
-export interface ScenarioRunStore {
-  /** Open a run. Called before the first scenario, with `status: 'running'`. */
-  start(record: ScenarioRunRecord): Promise<void>
-  /** Append one finished scenario to an open run. */
-  recordScenario(runId: string, result: ScenarioResult): Promise<void>
-  /**
-   * File the run's artifacts against the scenarios that produced them.
-   *
-   * Separate from `recordScenario` because a scenario's video does not exist
-   * when the scenario ends — it is finalised by the next scenario's reset, and
-   * renamed again when the run closes. Artifacts are matched to a result by the
-   * label the report knows it under.
-   */
-  attachArtifacts(runId: string, artifacts: ScenarioArtifact[]): Promise<void>
-  /** Close a run, settling everything only known once every scenario has run. */
-  finish(
-    runId: string,
-    outcome: Pick<
-      ScenarioRunRecord,
-      'status' | 'finishedAt' | 'skipped' | 'hookFailures'
-    >
-  ): Promise<void>
-  /**
-   * The bytes of one artifact, by the `path` its record carries.
-   *
-   * Reading goes through the store because only the store knows where a run's
-   * files actually are — a directory beside the project, or an object store
-   * behind a bucket. Absent when the run or the path is unknown, which is also
-   * the answer for a path that tries to leave the run.
-   *
-   * The bytes are backed by their own `ArrayBuffer` so they can be handed
-   * straight to a `Response` — a view onto a pooled or shared buffer is not a
-   * valid body.
-   */
-  readArtifact(
-    runId: string,
-    path: string
-  ): Promise<{ body: Uint8Array<ArrayBuffer>; contentType: string } | undefined>
-  /** Most recent first. */
-  list(options?: { limit?: number }): Promise<ScenarioRunSummary[]>
-  get(runId: string): Promise<ScenarioRunRecord | undefined>
-  /** Forget a run and everything it filed. */
-  remove(runId: string): Promise<void>
-}

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

@@ -1,147 +0,0 @@
-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() {} }
-
-const SCENARIO_MEMBERS = [
-  'scenarioStep',
-  'runScenarioHook',
-  'resolvePersonas',
-  'setScenarioBrowserProvider',
-  'getScenarioBrowserProvider',
-  'setScenarioEnvironment',
-  'getScenarioEnvironment',
-]
-
-const SCENARIO_WIRE_MEMBERS = [
-  '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-personas'),
-      '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)
-  })
-})