@pikku/core 0.12.69 → 0.12.71

package/src/wirings/workflow/feature.test.ts

@@ -0,0 +1,131 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { resolveFeatureScenarios } from './feature.js'
+import type { CoreFeature, CoreWorkflow } from './workflow.types.js'
+
+const scenario = (tags: string[] = []) =>
+  ({ tags, func: async () => ({}) }) as any
+
+const registered = (entries: Array<[string, any]>): Map<string, CoreWorkflow> =>
+  new Map(entries.map(([name, func]) => [name, { name, func }]))
+
+describe('resolveFeatureScenarios', () => {
+  test('resolves imported identifiers to the names they are registered under', () => {
+    const lazyLoad = scenario()
+    const roundTrip = scenario()
+    const features = new Map<string, CoreFeature>([
+      [
+        'credentialFeature',
+        {
+          name: 'Credential API',
+          scenarios: [lazyLoad, roundTrip],
+        },
+      ],
+    ])
+
+    const { entries, unresolved } = resolveFeatureScenarios(
+      features,
+      registered([
+        ['credentialLazyLoadScenario', lazyLoad],
+        ['credentialRoundTripScenario', roundTrip],
+      ])
+    )
+
+    assert.deepEqual(unresolved, [])
+    assert.deepEqual(
+      entries.map((e) => e.scenarioName),
+      ['credentialLazyLoadScenario', 'credentialRoundTripScenario']
+    )
+    assert.equal(entries[0]!.featureName, 'Credential API')
+    assert.equal(entries[0]!.featureId, 'credentialFeature')
+  })
+
+  test('keeps declaration order, including repeats of the same scenario', () => {
+    const roundTrip = scenario()
+    const features = new Map<string, CoreFeature>([
+      [
+        'credentialFeature',
+        {
+          name: 'Credential API',
+          scenarios: ['stripe', 'google', 'hmac-key'].map((name) => ({
+            scenario: roundTrip,
+            data: { name },
+          })),
+        },
+      ],
+    ])
+
+    const { entries } = resolveFeatureScenarios(
+      features,
+      registered([['credentialRoundTripScenario', roundTrip]])
+    )
+
+    assert.equal(entries.length, 3, 'a mapped loop is three separate runs')
+    assert.deepEqual(
+      entries.map((e) => e.data),
+      [{ name: 'stripe' }, { name: 'google' }, { name: 'hmac-key' }]
+    )
+    assert.ok(
+      entries.every((e) => e.scenarioName === 'credentialRoundTripScenario')
+    )
+  })
+
+  test('a bare reference carries no data', () => {
+    const lazyLoad = scenario()
+    const { entries } = resolveFeatureScenarios(
+      new Map([['f', { name: 'F', scenarios: [lazyLoad] } as CoreFeature]]),
+      registered([['lazyLoadScenario', lazyLoad]])
+    )
+    assert.equal(entries[0]!.data, undefined)
+  })
+
+  test("a scenario's effective tags union its own with the feature's", () => {
+    const lazyLoad = scenario(['scenario', 'credential'])
+    const { entries } = resolveFeatureScenarios(
+      new Map([
+        [
+          'f',
+          {
+            name: 'F',
+            tags: ['nightly', 'credential'],
+            scenarios: [lazyLoad],
+          } as CoreFeature,
+        ],
+      ]),
+      registered([['lazyLoadScenario', lazyLoad]])
+    )
+    assert.deepEqual(entries[0]!.tags, ['scenario', 'credential', 'nightly'])
+  })
+
+  test('an unregistered scenario is reported, never silently matched by shape', () => {
+    const registeredScenario = scenario()
+    const lookalike = scenario()
+    const { entries, unresolved } = resolveFeatureScenarios(
+      new Map([
+        [
+          'f',
+          {
+            name: 'F',
+            scenarios: [registeredScenario, lookalike],
+          } as CoreFeature,
+        ],
+      ]),
+      registered([['realScenario', registeredScenario]])
+    )
+    assert.deepEqual(
+      entries.map((e) => e.scenarioName),
+      ['realScenario']
+    )
+    assert.deepEqual(unresolved, [{ featureId: 'f', index: 1 }])
+  })
+
+  test('a feature with no scenarios contributes nothing', () => {
+    const { entries, unresolved } = resolveFeatureScenarios(
+      new Map([['f', { name: 'F', scenarios: [] } as CoreFeature]]),
+      registered([])
+    )
+    assert.deepEqual(entries, [])
+    assert.deepEqual(unresolved, [])
+  })
+})

package/src/wirings/workflow/feature.ts

@@ -0,0 +1,78 @@
+import { pikkuState } from '../../pikku-state.js'
+import type {
+  CoreFeature,
+  CoreWorkflow,
+  FeaturePlanEntry,
+} from './workflow.types.js'
+
+/**
+ * Register a feature under the name it is exported as. Called from generated
+ * wiring, the same way `addWorkflow` is.
+ */
+export const addFeature = (
+  featureId: string,
+  feature: CoreFeature,
+  packageName: string | null = null
+) => {
+  pikkuState(packageName, 'workflows', 'features').set(featureId, feature)
+}
+
+/**
+ * Resolve every feature's scenario references back to the names their
+ * scenarios are registered under.
+ *
+ * Matching is by **object identity**: `pikkuScenario` returns its config
+ * verbatim and `addWorkflow` registers that same object, so a feature holding
+ * the imported identifier holds the very object that was registered. Nothing
+ * is matched by shape, by name, or by any other guess — which is also why a
+ * scenario built inline inside a feature (and therefore never registered)
+ * comes back as unresolved rather than silently running as something else.
+ *
+ * Entries are returned in declaration order, features in registration order.
+ * A scenario's effective tags are its own plus the containing feature's, so
+ * `--tags credential` selects through the feature.
+ */
+export const resolveFeatureScenarios = (
+  features: Map<string, CoreFeature>,
+  registrations: Map<string, CoreWorkflow>
+): {
+  entries: FeaturePlanEntry[]
+  unresolved: Array<{ featureId: string; index: number }>
+} => {
+  const nameByConfig = new Map<unknown, string>()
+  for (const [name, registration] of registrations) {
+    nameByConfig.set(registration.func, name)
+  }
+
+  const entries: FeaturePlanEntry[] = []
+  const unresolved: Array<{ featureId: string; index: number }> = []
+
+  for (const [featureId, feature] of features) {
+    const scenarios = feature.scenarios ?? []
+    for (let index = 0; index < scenarios.length; index++) {
+      const entry = scenarios[index]!
+      const paired =
+        typeof entry === 'object' && entry !== null && 'scenario' in entry
+      const config = paired ? (entry as any).scenario : entry
+      const scenarioName = nameByConfig.get(config)
+      if (!scenarioName) {
+        unresolved.push({ featureId, index })
+        continue
+      }
+      entries.push({
+        featureId,
+        featureName: feature.name ?? featureId,
+        scenarioName,
+        data: paired ? (entry as any).data : undefined,
+        tags: [
+          ...new Set([
+            ...((registrations.get(scenarioName)?.func as any)?.tags ?? []),
+            ...(feature.tags ?? []),
+          ]),
+        ],
+      })
+    }
+  }
+
+  return { entries, unresolved }
+}

package/src/wirings/workflow/graph/graph-runner.ts

@@ -538,8 +538,9 @@ export async function continueGraph(
     return
   }
 
-  const run = await workflowService.getRun(runId)
-  const triggerInput = run?.input
+  // The same run read a few lines up: nothing between here and there writes it,
+  // and `input` is fixed at creation anyway.
+  const triggerInput = currentRun?.input
 
   for (const fire of plan.toFire) {
     const node = nodes[fire.logical]

package/src/wirings/workflow/graph/graph-validation.test.ts

@@ -1,150 +1,7 @@
 import { describe, it } from 'node:test'
 import assert from 'node:assert/strict'
 
-import {
-  computeEntryNodeIds,
-  validateWorkflowWiring,
-  generateMermaidDiagram,
-} from './graph-validation.js'
-
-describe('computeEntryNodeIds', () => {
-  it('returns nodes not referenced by any other node', () => {
-    const nodes = {
-      start: { rpcName: 'a', next: 'middle' },
-      middle: { rpcName: 'b', next: 'end' },
-      end: { rpcName: 'c' },
-    }
-    assert.deepEqual(computeEntryNodeIds(nodes), ['start'])
-  })
-
-  it('returns multiple entry nodes for parallel starts', () => {
-    const nodes = {
-      a: { rpcName: 'x' },
-      b: { rpcName: 'y' },
-      c: { rpcName: 'z', next: 'a' },
-    }
-    const entries = computeEntryNodeIds(nodes)
-    assert.ok(entries.includes('b'))
-    assert.ok(entries.includes('c'))
-    assert.ok(!entries.includes('a'))
-  })
-
-  it('returns empty for fully circular graph', () => {
-    const nodes = {
-      a: { rpcName: 'x', next: 'b' },
-      b: { rpcName: 'y', next: 'a' },
-    }
-    assert.deepEqual(computeEntryNodeIds(nodes), [])
-  })
-
-  it('handles onError references', () => {
-    const nodes = {
-      start: { rpcName: 'a', next: 'ok', onError: 'err' },
-      ok: { rpcName: 'b' },
-      err: { rpcName: 'c' },
-    }
-    assert.deepEqual(computeEntryNodeIds(nodes), ['start'])
-  })
-
-  it('handles branching next as object', () => {
-    const nodes = {
-      start: { rpcName: 'a', next: { yes: 'b', no: 'c' } },
-      b: { rpcName: 'x' },
-      c: { rpcName: 'y' },
-    }
-    assert.deepEqual(computeEntryNodeIds(nodes), ['start'])
-  })
-
-  it('handles parallel next as array', () => {
-    const nodes = {
-      start: { rpcName: 'a', next: ['b', 'c'] },
-      b: { rpcName: 'x' },
-      c: { rpcName: 'y' },
-    }
-    assert.deepEqual(computeEntryNodeIds(nodes), ['start'])
-  })
-})
-
-describe('validateWorkflowWiring', () => {
-  const tools = ['toolA', 'toolB', 'toolC']
-
-  it('returns no errors for a valid workflow', () => {
-    const nodes = {
-      step1: { rpcName: 'toolA', input: {}, next: 'step2' },
-      step2: { rpcName: 'toolB', input: {} },
-    }
-    const errors = validateWorkflowWiring(nodes, tools)
-    assert.deepEqual(errors, [])
-  })
-
-  it('errors on missing rpcName', () => {
-    const nodes = {
-      step1: { input: {} },
-    }
-    const errors = validateWorkflowWiring(nodes, tools)
-    assert.ok(errors.some((e) => e.includes("missing 'rpcName'")))
-  })
-
-  it('errors on unknown tool', () => {
-    const nodes = {
-      step1: { rpcName: 'unknownTool', input: {} },
-    }
-    const errors = validateWorkflowWiring(nodes, tools)
-    assert.ok(errors.some((e) => e.includes('unknown tool')))
-  })
-
-  it('errors on next referencing unknown node', () => {
-    const nodes = {
-      step1: { rpcName: 'toolA', next: 'nonexistent' },
-    }
-    const errors = validateWorkflowWiring(nodes, tools)
-    assert.ok(errors.some((e) => e.includes("unknown node 'nonexistent'")))
-  })
-
-  it('errors on onError referencing unknown node', () => {
-    const nodes = {
-      step1: { rpcName: 'toolA', onError: 'missing' },
-    }
-    const errors = validateWorkflowWiring(nodes, tools)
-    assert.ok(errors.some((e) => e.includes("unknown node 'missing'")))
-  })
-
-  it('errors on input referencing unknown node', () => {
-    const nodes = {
-      step1: {
-        rpcName: 'toolA',
-        input: { field: { $ref: 'missing', path: 'x' } },
-      },
-    }
-    const errors = validateWorkflowWiring(nodes, tools)
-    assert.ok(errors.some((e) => e.includes("unknown node 'missing'")))
-  })
-
-  it('allows trigger refs without errors', () => {
-    const nodes = {
-      step1: {
-        rpcName: 'toolA',
-        input: { field: { $ref: 'trigger', path: 'title' } },
-        next: 'step2',
-      },
-      step2: { rpcName: 'toolB', input: {} },
-    }
-    const errors = validateWorkflowWiring(nodes, tools)
-    assert.deepEqual(errors, [])
-  })
-
-  it('allows valid node-to-node refs', () => {
-    const nodes = {
-      step1: { rpcName: 'toolA', input: {}, next: 'step2' },
-      step2: {
-        rpcName: 'toolB',
-        input: { data: { $ref: 'step1', path: 'result' } },
-      },
-    }
-    const errors = validateWorkflowWiring(nodes, tools)
-    assert.deepEqual(errors, [])
-  })
-})
+import { generateMermaidDiagram } from './graph-validation.js'
 
 describe('generateMermaidDiagram', () => {
   it('generates valid mermaid output', () => {

package/src/wirings/workflow/graph/graph-validation.ts

@@ -1,6 +1,3 @@
-import { pikkuState } from '../../../pikku-state.js'
-import { resolveNamespace } from '../../rpc/rpc-runner.js'
-
 function normalizeTargets(value: unknown): string[] {
   if (!value) return []
   if (typeof value === 'string') return [value]
@@ -15,199 +12,6 @@ function normalizeTargets(value: unknown): string[] {
   return []
 }
 
-function collectRefs(value: unknown, refs: Set<string>): void {
-  if (
-    typeof value === 'object' &&
-    value !== null &&
-    '$ref' in value &&
-    typeof (value as any).$ref === 'string'
-  ) {
-    refs.add((value as any).$ref)
-    return
-  }
-  if (Array.isArray(value)) {
-    for (const item of value) collectRefs(item, refs)
-    return
-  }
-  if (typeof value === 'object' && value !== null) {
-    for (const v of Object.values(value)) collectRefs(v, refs)
-  }
-}
-
-function resolveToolMeta(toolName: string): {
-  fnMeta: any
-  schemas: Map<string, any>
-} | null {
-  const resolved = toolName.includes(':') ? resolveNamespace(toolName) : null
-
-  if (resolved) {
-    const fnMeta = pikkuState(resolved.package, 'function', 'meta')[
-      resolved.function
-    ]
-    const schemas = pikkuState(resolved.package, 'misc', 'schemas')
-    return fnMeta ? { fnMeta, schemas } : null
-  }
-
-  const rpcMeta = pikkuState(null, 'rpc', 'meta')
-  const pikkuFuncId = rpcMeta[toolName]
-  if (!pikkuFuncId) return null
-
-  const fnMeta = pikkuState(null, 'function', 'meta')[pikkuFuncId]
-  const schemas = pikkuState(null, 'misc', 'schemas')
-  return fnMeta ? { fnMeta, schemas } : null
-}
-
-export function computeEntryNodeIds(nodes: Record<string, any>): string[] {
-  const referenced = new Set<string>()
-  for (const node of Object.values(nodes)) {
-    if (node.next) {
-      for (const target of normalizeTargets(node.next)) {
-        referenced.add(target)
-      }
-    }
-    if (node.onError) {
-      for (const target of normalizeTargets(node.onError)) {
-        referenced.add(target)
-      }
-    }
-  }
-  return Object.keys(nodes).filter((id) => !referenced.has(id))
-}
-
-export function validateWorkflowWiring(
-  nodes: Record<string, any>,
-  toolNames: string[]
-): string[] {
-  const errors: string[] = []
-  const nodeIds = new Set(Object.keys(nodes))
-  const toolSet = new Set(toolNames)
-
-  for (const [nodeId, node] of Object.entries(nodes)) {
-    if (!node.rpcName) {
-      errors.push(`Node '${nodeId}' is missing 'rpcName'`)
-      continue
-    }
-
-    if (!toolSet.has(node.rpcName)) {
-      errors.push(
-        `Node '${nodeId}' references unknown tool '${node.rpcName}'. Available tools: ${toolNames.join(', ')}`
-      )
-      continue
-    }
-
-    const nextTargets = normalizeTargets(node.next)
-    for (const target of nextTargets) {
-      if (!nodeIds.has(target)) {
-        errors.push(
-          `Node '${nodeId}' routes to unknown node '${target}' in 'next'`
-        )
-      }
-    }
-
-    const errorTargets = normalizeTargets(node.onError)
-    for (const target of errorTargets) {
-      if (!nodeIds.has(target)) {
-        errors.push(
-          `Node '${nodeId}' routes to unknown node '${target}' in 'onError'`
-        )
-      }
-    }
-
-    if (!node.input) continue
-
-    const refs = new Set<string>()
-    collectRefs(node.input, refs)
-
-    for (const ref of refs) {
-      if (ref === 'trigger' || ref === '$item') {
-        const targetMeta = resolveToolMeta(node.rpcName)
-        if (targetMeta?.fnMeta?.inputSchemaName) {
-          const targetSchema = targetMeta.schemas.get(
-            targetMeta.fnMeta.inputSchemaName
-          )
-          if (targetSchema?.properties) {
-            for (const [field, fieldValue] of Object.entries(
-              node.input as Record<string, any>
-            )) {
-              if (
-                typeof fieldValue === 'object' &&
-                fieldValue !== null &&
-                fieldValue.$ref === ref &&
-                !fieldValue.path
-              ) {
-                const targetType = targetSchema.properties[field]?.type
-                if (targetType && targetType !== 'object') {
-                  errors.push(
-                    `Node '${nodeId}' input field '${field}' expects type '${targetType}', but references the whole ${ref} object without a path. Use { $ref: "${ref}", path: "${field}" } to extract the field.`
-                  )
-                }
-              }
-            }
-          }
-        }
-        continue
-      }
-
-      if (!nodeIds.has(ref)) {
-        errors.push(
-          `Node '${nodeId}' references unknown node '${ref}' in input`
-        )
-        continue
-      }
-
-      const sourceNode = nodes[ref]
-      if (!sourceNode?.rpcName) continue
-
-      const sourceMeta = resolveToolMeta(sourceNode.rpcName)
-      if (!sourceMeta?.fnMeta?.outputSchemaName) continue
-
-      const sourceSchema = sourceMeta.schemas.get(
-        sourceMeta.fnMeta.outputSchemaName
-      )
-      if (!sourceSchema?.properties) continue
-
-      for (const [field, fieldValue] of Object.entries(
-        node.input as Record<string, any>
-      )) {
-        if (
-          typeof fieldValue === 'object' &&
-          fieldValue !== null &&
-          fieldValue.$ref === ref &&
-          fieldValue.path
-        ) {
-          const pathRoot = fieldValue.path.split('.')[0]
-          if (
-            sourceSchema.properties &&
-            !(pathRoot in sourceSchema.properties)
-          ) {
-            errors.push(
-              `Node '${nodeId}' input field '${field}' references path '${fieldValue.path}' but node '${ref}' (${sourceNode.rpcName}) output has no property '${pathRoot}'`
-            )
-            continue
-          }
-
-          const targetMeta = resolveToolMeta(node.rpcName)
-          if (!targetMeta?.fnMeta?.inputSchemaName) continue
-          const targetSchema = targetMeta.schemas.get(
-            targetMeta.fnMeta.inputSchemaName
-          )
-          if (!targetSchema?.properties?.[field]) continue
-
-          const sourceType = sourceSchema.properties[pathRoot]?.type
-          const targetType = targetSchema.properties[field].type
-          if (sourceType && targetType && sourceType !== targetType) {
-            errors.push(
-              `Node '${nodeId}' input field '${field}' expects type '${targetType}', but node '${ref}' output field '${pathRoot}' is type '${sourceType}'`
-            )
-          }
-        }
-      }
-    }
-  }
-
-  return errors
-}
-
 export function generateMermaidDiagram(
   workflowName: string,
   nodes: Record<string, any>,

package/src/wirings/workflow/graph/index.ts

@@ -12,8 +12,4 @@ export {
   type PikkuWorkflowGraphConfig,
   type PikkuWorkflowGraphResult,
 } from './wire-workflow-graph.js'
-export {
-  validateWorkflowWiring,
-  computeEntryNodeIds,
-  generateMermaidDiagram,
-} from './graph-validation.js'
+export { generateMermaidDiagram } from './graph-validation.js'

package/src/wirings/workflow/index.ts

@@ -11,6 +11,11 @@ export {
   WorkflowApprovalResolvedError,
   DEFAULT_STEP_RETRIES,
 } from './pikku-workflow-service.js'
+export type {
+  RunLifecycleContext,
+  WorkflowRunEngine,
+  WorkflowRunExtension,
+} from './pikku-workflow-service.js'
 export { deriveInvocationId, uuidv5 } from './workflow-invocation-id.js'
 
 // Time-travel: reconstruct run state at any point from durable history
@@ -29,6 +34,7 @@ export type {
 
 // Internal registration functions (used by generated code)
 export { addWorkflow } from './dsl/workflow-runner.js'
+export { addFeature, resolveFeatureScenarios } from './feature.js'
 
 // Graph helpers (template, pikkuWorkflowGraph)
 export { template, type TemplateString } from './graph/template.js'
@@ -38,12 +44,6 @@ export {
   type PikkuWorkflowGraphResult,
 } from './graph/wire-workflow-graph.js'
 
-// Graph validation and dynamic workflow utilities
-export {
-  validateWorkflowWiring,
-  computeEntryNodeIds,
-} from './graph/graph-validation.js'
-
 // Queue worker functions (registered by codegen, executed at runtime)
 export {
   pikkuWorkflowWorkerFunc,
@@ -72,6 +72,12 @@ export type {
   WorkflowRunService,
   WorkflowRunMirror,
   CoreWorkflow,
+  CoreFeature,
+  CoreFeatureScenario,
+  FeatureMeta,
+  FeatureMetaEntry,
+  FeaturesMeta,
+  FeaturePlanEntry,
   PikkuWorkflow,
   ContextVariable,
   WorkflowContext,
@@ -113,8 +119,69 @@ export type {
   SwitchStepMeta,
   FilterStepMeta,
   ArrayPredicateStepMeta,
+  ScenarioStepInvocation,
+  ScenarioStepMeta,
   WorkflowStepMeta,
   WorkflowStepWire,
   PikkuWorkflowWire,
   PikkuScenarioWire,
 } from './workflow.types.js'
+
+/* ------------------------------------------------------------------ *
+ * Scenarios — writing a step
+ *
+ * What a step file imports. Everything here is reached from inside a
+ * `pikkuScenarioStep` body.
+ * ------------------------------------------------------------------ */
+
+// The step's own wire, and the shape of what it was given
+export type {
+  ScenarioStepPhase,
+  ScenarioStepOptions,
+  PikkuScenarioStepWire,
+  ScenarioEnvironment,
+} from './scenario-step.types.js'
+
+// Narrows the optional halves of the step wire, with a message that says what to do
+export { requireActor, requireScenarioEnv } from './scenario-step-guards.js'
+
+// Waits for the target to catch up, without every step writing the loop again
+export { pollUntil, type PollOptions } from './scenario-poll.js'
+
+// Persists cookies across a step's requests, the way a browser would
+export { createCookieJar } from './scenario-cookie-jar.js'
+export type { ScenarioCookieJar } from './scenario-cookie-jar.js'
+
+// What the transport answered — an actor's `invokeRaw`, or a route reached
+// directly — and the one way to POST JSON at a route and keep its status
+export type {
+  ScenarioHttpResponse,
+  ScenarioJsonRequest,
+} from '../../services/scenario-actors-service.js'
+export {
+  readScenarioHttpResponse,
+  postScenarioJson,
+} from '../../services/scenario-actors-service.js'
+
+/* ------------------------------------------------------------------ *
+ * Scenarios — driving a browser
+ *
+ * How a step names an element, and what a driver package
+ * (`@pikku/playwright`, or another) implements.
+ * ------------------------------------------------------------------ */
+
+export type {
+  PikkuBrowserWire,
+  TestIdSelector,
+  ScenarioBrowserProvider,
+  ScenarioBrowserFailure,
+} from './scenario-step.types.js'
+
+/* ------------------------------------------------------------------ *
+ * Scenarios — reporting a run
+ *
+ * Used by the CLI reporter and the console, so the two render the same
+ * sentence for the same step. A step body needs none of it.
+ * ------------------------------------------------------------------ */
+
+export { composeStepProse, renderStepTemplate } from './scenario-prose.js'