@pikku/inspector 0.12.47 → 0.12.49

package/src/utils/workflow/dsl/extract-dsl-workflow.ts

@@ -15,6 +15,7 @@ import type {
   SwitchCaseMeta,
   FilterStepMeta,
   ArrayPredicateStepMeta,
+  ScenarioStepMeta,
   InputSource,
   OutputBinding,
   Condition,
@@ -24,6 +25,9 @@ import type {
 import {
   isWorkflowDoCall,
   isWorkflowExpectEventuallyCall,
+  isScenarioStepCall,
+  getScenarioStepPhase,
+  DYNAMIC_SCENARIO_STEP_TARGET,
   extractActorFromOptions,
   isWorkflowSleepCall,
   isWorkflowSuspendCall,
@@ -60,7 +64,7 @@ interface ExtractionContext {
   outputVars: Map<string, { type: ts.Type; node: ts.Node }>
   arrayVars: Set<string>
   conditionalVars: Set<string>
-  inputParamName: string
+  inputParamName: string | null
   errors: ValidationError[]
   /** Loop variables in scope (for fanout item variables) */
   loopVars: Set<string>
@@ -101,7 +105,7 @@ export function extractDSLWorkflow(
 
     // Extract input parameter name (second parameter)
     const inputParamName = extractInputParamName(arrowFunc)
-    if (!inputParamName) {
+    if (inputParamName === undefined) {
       return {
         status: 'error',
         reason: 'Could not determine input parameter name',
@@ -220,9 +224,17 @@ function findWorkflowFunction(node: ts.Node): ts.ArrowFunction | null {
 }
 
 /**
- * Extract the input parameter name from the arrow function
+ * Extract the input parameter name from the arrow function.
+ *
+ * Returns `null` when no input parameter is declared at all. That is
+ * legitimate — a workflow may ignore its input — and nothing in the body can
+ * reference it, so every name comparison against `null` correctly fails.
+ * Returns `undefined` when an input parameter is declared but is not a plain
+ * identifier (destructured), which the extractor cannot track by name.
  */
-function extractInputParamName(arrowFunc: ts.ArrowFunction): string | null {
+function extractInputParamName(
+  arrowFunc: ts.ArrowFunction
+): string | null | undefined {
   if (arrowFunc.parameters.length < 2) {
     return null
   }
@@ -232,7 +244,7 @@ function extractInputParamName(arrowFunc: ts.ArrowFunction): string | null {
     return secondParam.name.text
   }
 
-  return null
+  return undefined
 }
 
 /**
@@ -298,7 +310,34 @@ function extractStep(
 
   // For-of statement (sequential fanout)
   if (ts.isForOfStatement(statement)) {
-    return extractSequentialFanout(statement, context)
+    const reason: { message?: string } = {}
+    const fanout = extractSequentialFanout(statement, context, reason)
+    if (!fanout && containsWorkflowCall(statement.statement, context.checker)) {
+      // A for-of the DSL can't model as a sequential fanout (its iterable is not
+      // a data-array identifier/field — e.g. a counting loop
+      // `for (const i of [...Array(N).keys()])`). Silently returning null here
+      // used to drop the loop AND every `workflow.do` inside it, so the workflow
+      // serialized with zero steps and its step functions were never registered
+      // (→ runtime "Function not found"). Fail loudly instead: pikkuWorkflowFunc
+      // reports INVALID_DSL_WORKFLOW; pikkuWorkflowComplexFunc falls back to the
+      // basic AST walk (which DOES register loop-invoked functions), so a genuine
+      // control-flow loop belongs in a complex workflow.
+      //
+      // Guarded on the body actually containing a workflow call: a loop that only
+      // massages locals (building a lookup, summing a total) has no step to lose,
+      // and erroring on it would be a false positive — the whole hazard is a
+      // dropped `workflow.do`, not a dropped `for`.
+      context.errors.push({
+        message:
+          `The for-of loop '${statement.getText().slice(0, 60)}' can't be expressed in a DSL workflow — ` +
+          (reason.message ??
+            `its iterable must be a data array (an identifier or field like 'data.items'), not a computed/inline ` +
+              `iterable such as '[...Array(n).keys()]'. Use pikkuWorkflowComplexFunc for a control-flow/counting loop, ` +
+              `or iterate over a real input array.`),
+        node: statement,
+      })
+    }
+    return fanout
   }
 
   // Return statement
@@ -363,10 +402,12 @@ function extractVariableDeclaration(
   // Check for await workflow.do(...)
   if (ts.isAwaitExpression(init) && ts.isCallExpression(init.expression)) {
     const call = init.expression
-    if (isWorkflowDoCall(call, context.checker)) {
-      const step = isInlineDoCall(call)
-        ? extractInlineStep(call, context)
-        : extractRpcStep(call, context, varName)
+    if (isWorkflowDoCall(call, context.checker) || isScenarioStepCall(call)) {
+      const step = isScenarioStepCall(call)
+        ? extractScenarioStep(call, context, varName)
+        : isInlineDoCall(call)
+          ? extractInlineStep(call, context)
+          : extractRpcStep(call, context, varName)
       if (step) {
         // Track output variable
         const type = context.checker.getTypeAtLocation(decl)
@@ -515,6 +556,7 @@ function extractDestructuredDeclaration(
   const destructuresAStep =
     stepCall !== null &&
     (isWorkflowDoCall(stepCall, context.checker) ||
+      isScenarioStepCall(stepCall) ||
       isParallelGroup(stepCall) ||
       isParallelFanout(stepCall))
   if (!destructuresAStep) return null
@@ -584,10 +626,12 @@ function extractExpressionStatement(
   if (ts.isAwaitExpression(expr) && ts.isCallExpression(expr.expression)) {
     const call = expr.expression
 
-    if (isWorkflowDoCall(call, context.checker)) {
-      const step = isInlineDoCall(call)
-        ? extractInlineStep(call, context)
-        : extractRpcStep(call, context, outputVar)
+    if (isWorkflowDoCall(call, context.checker) || isScenarioStepCall(call)) {
+      const step = isScenarioStepCall(call)
+        ? extractScenarioStep(call, context, outputVar)
+        : isInlineDoCall(call)
+          ? extractInlineStep(call, context)
+          : extractRpcStep(call, context, outputVar)
 
       // Track output variable if this is an assignment
       if (outputVar && step) {
@@ -692,6 +736,68 @@ function extractRpcStep(
   }
 }
 
+/**
+ * Extract a scenario step from scenario.step/given/when/then(stepName,
+ * stepFunc, data?, options?).
+ *
+ * The step target must be a static string literal so it can be bundled, typed
+ * and drawn. When it isn't, the step is still recorded — with a `<dynamic>`
+ * target — so post-processing can raise PKU678 rather than the call silently
+ * vanishing from the graph.
+ */
+function extractScenarioStep(
+  call: ts.CallExpression,
+  context: ExtractionContext,
+  outputVar?: string
+): ScenarioStepMeta | null {
+  const phase = getScenarioStepPhase(call)
+  if (!phase) {
+    return null
+  }
+
+  const args = call.arguments
+  if (args.length < 2) {
+    return null
+  }
+
+  try {
+    const stepName = extractStringLiteral(args[0], context.checker)
+
+    let stepFunc = DYNAMIC_SCENARIO_STEP_TARGET
+    try {
+      stepFunc = extractStringLiteral(args[1], context.checker)
+    } catch {
+      // Left as '<dynamic>' — validated in post-processing (PKU678).
+    }
+
+    const inputs =
+      args.length >= 3 ? extractInputSources(args[2], context) : undefined
+
+    const optionsArg = args.length >= 4 ? args[3] : undefined
+    const options =
+      optionsArg && ts.isObjectLiteralExpression(optionsArg)
+        ? extractStepOptions(optionsArg, context)
+        : undefined
+
+    return {
+      type: 'scenarioStep',
+      stepName,
+      stepFunc,
+      phase,
+      outputVar,
+      inputs,
+      options,
+      actor: extractActorFromOptions(optionsArg),
+    }
+  } catch (error) {
+    context.errors.push({
+      message: `Failed to extract scenario step: ${error instanceof Error ? error.message : String(error)}`,
+      node: call,
+    })
+    return null
+  }
+}
+
 /**
  * Extract inline step from workflow.do() call with a function argument
  */
@@ -1225,7 +1331,7 @@ function extractArrayPredicate(
 function extractFanoutBodyStep(
   stmt: ts.Statement,
   childContext: ExtractionContext,
-  body: Array<RpcStepMeta | SleepStepMeta | SuspendStepMeta>
+  body: Array<RpcStepMeta | SleepStepMeta | SuspendStepMeta | ScenarioStepMeta>
 ): void {
   if (ts.isVariableStatement(stmt)) {
     const declList = stmt.declarationList
@@ -1242,11 +1348,16 @@ function extractFanoutBodyStep(
       return
     }
     const call = init.expression
-    if (!isWorkflowDoCall(call, childContext.checker)) {
+    if (
+      !isWorkflowDoCall(call, childContext.checker) &&
+      !isScenarioStepCall(call)
+    ) {
       return
     }
     const varName = ts.isIdentifier(decl.name) ? decl.name.text : undefined
-    const step = extractRpcStep(call, childContext, varName)
+    const step = isScenarioStepCall(call)
+      ? extractScenarioStep(call, childContext, varName)
+      : extractRpcStep(call, childContext, varName)
     if (!step) {
       return
     }
@@ -1290,6 +1401,13 @@ function extractFanoutBodyStep(
       }
       return
     }
+    if (isScenarioStepCall(call)) {
+      const scenarioStep = extractScenarioStep(call, childContext)
+      if (scenarioStep) {
+        body.push(scenarioStep)
+      }
+      return
+    }
     if (!isWorkflowDoCall(call, childContext.checker)) {
       return
     }
@@ -1363,7 +1481,12 @@ function extractParallelFanout(
         ? expr
         : null
 
-    if (doCall && isWorkflowDoCall(doCall, context.checker)) {
+    if (doCall && isScenarioStepCall(doCall)) {
+      const step = extractScenarioStep(doCall, childContext)
+      if (step) {
+        body.push(step)
+      }
+    } else if (doCall && isWorkflowDoCall(doCall, context.checker)) {
       const step = extractRpcStep(doCall, childContext)
       if (step) {
         body.push(step)
@@ -1396,10 +1519,18 @@ function extractParallelGroup(
     return null
   }
 
-  const children: RpcStepMeta[] = []
+  const children: Array<RpcStepMeta | ScenarioStepMeta> = []
 
   for (const elem of arrayArg.elements) {
-    if (ts.isCallExpression(elem) && isWorkflowDoCall(elem, context.checker)) {
+    if (!ts.isCallExpression(elem)) {
+      continue
+    }
+    if (isScenarioStepCall(elem)) {
+      const step = extractScenarioStep(elem, context)
+      if (step) {
+        children.push(step)
+      }
+    } else if (isWorkflowDoCall(elem, context.checker)) {
       const step = extractRpcStep(elem, context)
       if (step) {
         children.push(step)
@@ -1420,9 +1551,40 @@ function extractParallelGroup(
 /**
  * Extract sequential fanout from for-of loop
  */
+/**
+ * Does this subtree call the workflow wire at all?
+ *
+ * Used to tell "the DSL can't model this loop, and a step would be silently
+ * lost" from "the DSL can't model this loop, and there is nothing in it to
+ * lose". Only the first is worth failing a build over.
+ */
+function containsWorkflowCall(node: ts.Node, checker: ts.TypeChecker): boolean {
+  let found = false
+  const visit = (child: ts.Node): void => {
+    if (found) return
+    if (ts.isCallExpression(child)) {
+      if (
+        isWorkflowDoCall(child, checker) ||
+        isScenarioStepCall(child) ||
+        isWorkflowSleepCall(child, checker) ||
+        isWorkflowSuspendCall(child, checker) ||
+        isWorkflowApprovalCall(child, checker) ||
+        isWorkflowExpectEventuallyCall(child)
+      ) {
+        found = true
+        return
+      }
+    }
+    ts.forEachChild(child, visit)
+  }
+  visit(node)
+  return found
+}
+
 function extractSequentialFanout(
   statement: ts.ForOfStatement,
-  context: ExtractionContext
+  context: ExtractionContext,
+  reason?: { message?: string }
 ): FanoutStepMeta | null {
   if (!isSequentialFanout(statement)) {
     return null
@@ -1521,6 +1683,18 @@ function extractSequentialFanout(
   }
 
   if (body.length === 0) {
+    // The iterable was fine — the body yielded nothing the DSL can model. The
+    // usual cause is a `workflow.do` nested inside an `if`/`switch`, because
+    // `FanoutStepMeta['body']` is a flat list of steps with no branch member:
+    // the DSL has no way to say "conditionally run this step per item".
+    const branching = bodyStatements.some(
+      (stmt) => ts.isIfStatement(stmt) || ts.isSwitchStatement(stmt)
+    )
+    if (reason) {
+      reason.message = branching
+        ? `its body only calls 'workflow.do' inside an if/switch, and a DSL fanout body is a flat list of steps with no branch member — the DSL cannot express a per-item condition. Use pikkuWorkflowComplexFunc, or lift the condition out of the loop.`
+        : `its body contains no 'workflow.do' call the DSL can model. Use pikkuWorkflowComplexFunc for a loop that does other work.`
+    }
     return null
   }
 
@@ -1741,7 +1915,11 @@ function extractInputSources(
         } else if (context.outputVars.has(varName)) {
           source = { from: 'outputVar', name: varName }
         } else {
-          source = { from: 'input', path: varName }
+          const constant = resolveConstantValue(prop.name, context.checker)
+          source =
+            constant !== undefined
+              ? { from: 'literal', value: constant }
+              : { from: 'input', path: varName }
         }
       } else if (ts.isPropertyAssignment(prop)) {
         source = extractInputSource(prop.initializer, context)
@@ -1831,6 +2009,11 @@ function extractInputSource(
       return { from: 'outputVar', name: varName }
     }
 
+    const constant = resolveConstantValue(node, context.checker)
+    if (constant !== undefined) {
+      return { from: 'literal', value: constant }
+    }
+
     // Assume it's from input
     return { from: 'input', path: varName }
   }
@@ -1916,6 +2099,37 @@ function extractInputSource(
   return null
 }
 
+/**
+ * Resolve an identifier that names a constant to the value it was declared with.
+ *
+ * Without this, a name the extractor does not recognise falls through to
+ * `{ from: 'input' }` and is serialized as `{ $ref: 'trigger', path: <name> }` —
+ * so a module-level `const RESOURCE_ID = 'x'` used as step input silently
+ * becomes a read of a trigger field that does not exist. Only `const`
+ * declarations with a fully literal initializer resolve; anything else (a name
+ * bound out of the trigger, a computed value) falls through unchanged.
+ */
+function resolveConstantValue(
+  node: ts.Identifier,
+  checker: ts.TypeChecker
+): unknown | undefined {
+  const symbol = checker.getSymbolAtLocation(node)
+  const declaration = symbol?.valueDeclaration ?? symbol?.declarations?.[0]
+  if (!declaration || !ts.isVariableDeclaration(declaration)) {
+    return undefined
+  }
+  const declarationList = declaration.parent
+  if (
+    !ts.isVariableDeclarationList(declarationList) ||
+    !(declarationList.flags & ts.NodeFlags.Const)
+  ) {
+    return undefined
+  }
+  return declaration.initializer
+    ? extractLiteralValue(declaration.initializer)
+    : undefined
+}
+
 /**
  * Extract a literal value from an expression
  */

package/src/utils/workflow/dsl/patterns.ts

@@ -36,6 +36,44 @@ export function isWorkflowDoCall(
   )
 }
 
+/**
+ * Placeholder recorded when a scenario step's target isn't a static string
+ * literal. The step is kept rather than dropped so post-processing can raise
+ * PKU678 against it — a dropped step is the silent-failure mode this repo has
+ * hit repeatedly on workflow graph round-trips.
+ */
+export const DYNAMIC_SCENARIO_STEP_TARGET = '<dynamic>'
+
+const SCENARIO_STEP_PHASES = ['step', 'given', 'when', 'then'] as const
+
+export type ScenarioStepPhaseName = (typeof SCENARIO_STEP_PHASES)[number]
+
+/**
+ * Check if a call expression is scenario.step()/given()/when()/then() — a
+ * declared `pikkuScenarioStep` invoked by name. `given`/`when`/`then` are pure
+ * sugar over `step`: the phase only changes the prose a reporter renders.
+ */
+export function isScenarioStepCall(node: ts.CallExpression): boolean {
+  return getScenarioStepPhase(node) !== undefined
+}
+
+/**
+ * The Gherkin-style phase of a scenario step call, or undefined when the call
+ * isn't one.
+ */
+export function getScenarioStepPhase(
+  node: ts.CallExpression
+): ScenarioStepPhaseName | undefined {
+  if (!ts.isPropertyAccessExpression(node.expression)) {
+    return
+  }
+  const propAccess = node.expression
+  if (!isWorkflowWireIdentifier(propAccess.expression)) {
+    return
+  }
+  return SCENARIO_STEP_PHASES.find((phase) => phase === propAccess.name.text)
+}
+
 /**
  * Check if a call expression is workflow.expectEventually()
  */

package/src/utils/workflow/dsl/validation.ts

@@ -22,6 +22,11 @@ export interface ValidationError {
  * - ReturnStatement
  * - ThrowStatement (for WorkflowCancelledException)
  * - Block (containers)
+ *
+ * When `allowInline` is set (complex workflows and scenarios), the bodies of
+ * closures are skipped: a callback is ordinary TypeScript, not DSL, so holding
+ * it to the statement whitelist would reject valid code. Plain DSL workflows
+ * still descend into callbacks, which is what validates fanout bodies.
  */
 export function validateNoDisallowedPatterns(
   node: ts.Node,
@@ -54,6 +59,13 @@ export function validateNoDisallowedPatterns(
   }
 
   function visitNode(node: ts.Node) {
+    if (
+      options?.allowInline &&
+      (ts.isArrowFunction(node) || ts.isFunctionExpression(node))
+    ) {
+      return
+    }
+
     // Disallow while and do-while
     if (ts.isWhileStatement(node) || ts.isDoStatement(node)) {
       errors.push({

package/src/utils/workflow/graph/convert-dsl-to-graph-skip.test.ts

@@ -0,0 +1,35 @@
+import { test } from 'node:test'
+import assert from 'node:assert'
+import { convertDslToGraph } from './convert-dsl-to-graph.js'
+import type { WorkflowsMeta } from '@pikku/core'
+
+const scenarioMeta = (
+  overrides: Partial<WorkflowsMeta[string]> = {}
+): WorkflowsMeta[string] => ({
+  pikkuFuncId: 'installAddonFreshNameScenario',
+  name: 'installAddonFreshNameScenario',
+  scenario: true,
+  steps: [],
+  ...overrides,
+})
+
+test('convertDslToGraph: a scenario carries its skip reason into the graph', () => {
+  const graph = convertDslToGraph(
+    'installAddonFreshNameScenario',
+    scenarioMeta({ skip: 'npm cannot install inside this yarn workspace' })
+  )
+
+  assert.strictEqual(
+    graph.skip,
+    'npm cannot install inside this yarn workspace'
+  )
+})
+
+test('convertDslToGraph: a scenario with no skip leaves it unset', () => {
+  const graph = convertDslToGraph(
+    'installAddonFreshNameScenario',
+    scenarioMeta()
+  )
+
+  assert.strictEqual(graph.skip, undefined)
+})

package/src/utils/workflow/graph/convert-dsl-to-graph.ts

@@ -138,6 +138,41 @@ function convertStepToNode(
       return [node]
     }
 
+    // A declared step is a function node like any other — the console draws it
+    // the same way, with the phase available for the "Given/When/Then" prose.
+    case 'scenarioStep': {
+      const node: FunctionNode = {
+        nodeId,
+        rpcName: step.stepFunc,
+        stepName: step.stepName,
+        scenarioStepPhase: step.phase,
+        next: nextNodeId,
+      }
+      if (step.actor) {
+        node.actor = step.actor
+      }
+      if (step.inputs) {
+        if (step.inputs === 'passthrough') {
+          node.input = { $passthrough: { $ref: 'trigger' } }
+        } else {
+          node.input = {}
+          for (const [key, source] of Object.entries(step.inputs)) {
+            node.input[key] = convertInputSource(source as any)
+          }
+        }
+      }
+      if (step.outputVar) {
+        node.outputVar = step.outputVar
+      }
+      if (step.options) {
+        node.options = {
+          retries: step.options.retries,
+          retryDelay: step.options.retryDelay,
+        }
+      }
+      return [node]
+    }
+
     case 'sleep': {
       const node: FlowNode = {
         nodeId,
@@ -484,6 +519,7 @@ export function convertDslToGraph(
     title: meta.title,
     description: meta.description,
     tags: meta.tags,
+    skip: meta.skip,
     actors: meta.actors,
     context: meta.context,
     nodes: nodesRecord,

package/src/utils/workflow/graph/workflow-graph.types.ts

@@ -113,6 +113,7 @@ export type FlowType =
 // Import and re-export context types from core
 import type {
   ContextVariable,
+  ScenarioStepPhase,
   WorkflowContext,
   WorkflowPlannedStep,
 } from '@pikku/core/workflow'
@@ -153,6 +154,8 @@ export interface FunctionNode extends BaseNode {
   actor?: string
   /** True for workflow.expectEventually polling steps (scenarios) */
   expectEventually?: boolean
+  /** Gherkin-style phase for a declared scenario step (scenario.given/when/then) */
+  scenarioStepPhase?: ScenarioStepPhase
 }
 
 /**
@@ -210,6 +213,8 @@ export interface SerializedWorkflowGraph {
   tags?: string[]
   /** Actor names a scenario's steps run as */
   actors?: string[]
+  /** Why a scenario is held out of a default run, stated where it is declared */
+  skip?: string
   /** If true, workflow always executes inline without queues */
   inline?: boolean
   /** Workflow context/state variables (from Zod schema) */

package/src/visit.ts

@@ -30,6 +30,7 @@ import { addCredential } from './add/add-credential.js'
 import { addScope } from './add/add-scope.js'
 import { addVariable } from './add/add-variable.js'
 import { addWorkflowGraph } from './add/add-workflow-graph.js'
+import { addFeature } from './add/add-feature.js'
 import { addAIAgent } from './add/add-ai-agent.js'
 import { addApprovalDescription } from './add/add-approval-description.js'
 
@@ -165,6 +166,7 @@ export const visitRoutes = (
   addMCPResource(logger, node, checker, state, nextOptions)
   addMCPPrompt(logger, node, checker, state, nextOptions)
   addWorkflowGraph(logger, node, checker, state, nextOptions)
+  addFeature(logger, node, checker, state, nextOptions)
   addAIAgent(logger, node, checker, state, nextOptions)
 
   ts.forEachChild(node, (child) =>