@pikku/inspector 0.12.42 → 0.12.44

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

@@ -8,6 +8,8 @@ import type {
   FanoutStepMeta,
   CancelStepMeta,
   SuspendStepMeta,
+  SleepStepMeta,
+  ApprovalStepMeta,
   SetStepMeta,
   SwitchStepMeta,
   SwitchCaseMeta,
@@ -25,6 +27,7 @@ import {
   extractActorFromOptions,
   isWorkflowSleepCall,
   isWorkflowSuspendCall,
+  isWorkflowApprovalCall,
   isThrowCancelException,
   extractCancelReason,
   isParallelFanout,
@@ -320,12 +323,16 @@ function extractVariableDeclaration(
 ): WorkflowStepMeta | null {
   const declList = statement.declarationList
   if (declList.declarations.length !== 1) {
+    context.errors.push({
+      message: `A single declaration statement may only declare one variable in DSL workflows. Split '${statement.getText().slice(0, 60)}' into separate statements.`,
+      node: statement,
+    })
     return null
   }
 
   const decl = declList.declarations[0]
   if (!ts.isIdentifier(decl.name)) {
-    return null
+    return extractDestructuredDeclaration(statement, decl, context)
   }
 
   const varName = decl.name.text
@@ -435,6 +442,70 @@ function extractVariableDeclaration(
   return null
 }
 
+/**
+ * Extract a declaration whose binding is a destructuring pattern.
+ *
+ * `const [a, b] = await Promise.all([...])` is the idiomatic way to run steps
+ * in parallel and keep both results, so each element of the pattern is bound to
+ * the matching child step's output. Every other destructuring shape reports a
+ * diagnostic rather than silently dropping the step.
+ */
+function extractDestructuredDeclaration(
+  statement: ts.VariableStatement,
+  decl: ts.VariableDeclaration,
+  context: ExtractionContext
+): WorkflowStepMeta | null {
+  const init = decl.initializer
+
+  if (
+    init &&
+    ts.isAwaitExpression(init) &&
+    ts.isCallExpression(init.expression) &&
+    isParallelGroup(init.expression) &&
+    ts.isArrayBindingPattern(decl.name)
+  ) {
+    const elements = decl.name.elements
+    const allSimple = elements.every(
+      (el) =>
+        ts.isBindingElement(el) &&
+        ts.isIdentifier(el.name) &&
+        !el.dotDotDotToken
+    )
+
+    if (allSimple) {
+      const step = extractParallelGroup(init.expression, context)
+      if (step) {
+        if (elements.length !== step.children.length) {
+          context.errors.push({
+            message: `Destructuring binds ${elements.length} name(s) but Promise.all has ${step.children.length} step(s). They must match so each result can be bound to its step.`,
+            node: statement,
+          })
+          return null
+        }
+
+        elements.forEach((el, i) => {
+          const name = (el as ts.BindingElement).name as ts.Identifier
+          const varName = name.text
+          step.children[i].outputVar = varName
+          const type = context.checker.getTypeAtLocation(name)
+          context.outputVars.set(varName, { type, node: name })
+          if (isArrayType(type, context.checker)) {
+            context.arrayVars.add(varName)
+          }
+        })
+
+        return step
+      }
+    }
+  }
+
+  context.errors.push({
+    message: `Destructuring a step result is not supported in DSL workflows. Assign it to a variable first (e.g. \`const result = await workflow.do(...)\`) and read its properties.`,
+    node: statement,
+  })
+  return null
+}
+
 /**
  * Extract expression statement (await workflow.do(...) without assignment)
  */
@@ -476,11 +547,11 @@ function extractExpressionStatement(
               value: literalValue,
             } as SetStepMeta
           }
-          // Non-literal assignment to context var - use expression as string
+          // Non-literal assignment to context var - keep the source expression
           return {
             type: 'set',
             variable: outputVar,
-            value: getSourceText(expr.right),
+            expression: getSourceText(expr.right),
           } as SetStepMeta
         }
       }
@@ -520,6 +591,22 @@ function extractExpressionStatement(
       return extractSuspendStep(call, context)
     }
 
+    if (isWorkflowApprovalCall(call, context.checker)) {
+      const step = extractApprovalStep(call, context, outputVar)
+
+      // Unlike suspend, an approval yields a value, so a downstream step can
+      // reference it — track the binding the same way workflow.do() does.
+      if (outputVar && step) {
+        const type = context.checker.getTypeAtLocation(expr)
+        context.outputVars.set(outputVar, { type, node: expr })
+        if (isArrayType(type, context.checker)) {
+          context.arrayVars.add(outputVar)
+        }
+      }
+
+      return step
+    }
+
     // Check for parallel group or fanout
     if (isParallelFanout(call)) {
       return extractParallelFanout(call, context)
@@ -659,6 +746,16 @@ function extractStepOptions(
         } catch {
           // Ignore extraction errors for retryDelay
         }
+      } else if (propName === 'onError') {
+        if (ts.isStringLiteral(prop.initializer)) {
+          options.onError = prop.initializer.text
+        } else {
+          context.errors.push({
+            message:
+              'onError must be a literal RPC name so it can be wired and drawn in the graph.',
+            node: prop.initializer,
+          })
+        }
       } else if (propName === 'description') {
         try {
           options.description = extractStringLiteral(
@@ -696,7 +793,19 @@ function extractSleepStep(
     if (numValue !== null) {
       duration = numValue
     } else {
-      duration = extractStringLiteral(args[1], context.checker)
+      try {
+        duration = extractStringLiteral(args[1], context.checker)
+      } catch {
+        // A duration computed at runtime (a loop variable, a field off the
+        // input) is legal: the closure evaluates it. Record the source text so
+        // the graph can show what it waits on, rather than failing the workflow.
+        return {
+          type: 'sleep',
+          stepName,
+          duration: '',
+          expression: args[1].getText(),
+        }
+      }
     }
 
     return {
@@ -738,6 +847,54 @@ function extractSuspendStep(
   }
 }
 
+/**
+ * Extract approval step from workflow.approval() call
+ */
+function extractApprovalStep(
+  call: ts.CallExpression,
+  context: ExtractionContext,
+  outputVar?: string
+): ApprovalStepMeta | null {
+  const args = call.arguments
+  if (args.length < 1) return null
+
+  try {
+    const reason = extractStringLiteral(args[0], context.checker)
+    const step: ApprovalStepMeta = {
+      type: 'approval',
+      reason,
+    }
+    if (outputVar) {
+      step.outputVar = outputVar
+    }
+    // The `schema` option is a runtime value validated inside the workflow body,
+    // so it is deliberately not serialized here — only `expiry`, which the graph
+    // and planned-step ladder need in order to describe the gate.
+    const options = args[1]
+    if (options && ts.isObjectLiteralExpression(options)) {
+      for (const prop of options.properties) {
+        if (
+          ts.isPropertyAssignment(prop) &&
+          prop.name.getText() === 'expiry' &&
+          (ts.isStringLiteral(prop.initializer) ||
+            ts.isNumericLiteral(prop.initializer))
+        ) {
+          step.expiry = ts.isNumericLiteral(prop.initializer)
+            ? Number(prop.initializer.text)
+            : prop.initializer.text
+        }
+      }
+    }
+    return step
+  } catch (error) {
+    context.errors.push({
+      message: `Failed to extract approval step: ${error instanceof Error ? error.message : String(error)}`,
+      node: call,
+    })
+    return null
+  }
+}
+
 /**
  * Extract cancel step from throw WorkflowCancelledException statement
  */
@@ -1037,6 +1194,92 @@ function extractArrayPredicate(
   }
 }
 
+/**
+ * Extract an ordered list of workflow.do steps from a per-iteration body.
+ *
+ * Unlike if/switch blocks, a fanout body is a real per-iteration scope, so
+ * `const x = await workflow.do(...)` is meaningful here: the binding is
+ * registered on the child context so later steps in the same iteration can
+ * reference it.
+ */
+function extractFanoutBodyStep(
+  stmt: ts.Statement,
+  childContext: ExtractionContext,
+  body: Array<RpcStepMeta | SleepStepMeta | SuspendStepMeta>
+): void {
+  if (ts.isVariableStatement(stmt)) {
+    const declList = stmt.declarationList
+    if (declList.declarations.length !== 1) {
+      return
+    }
+    const decl = declList.declarations[0]
+    const init = decl.initializer
+    if (
+      !init ||
+      !ts.isAwaitExpression(init) ||
+      !ts.isCallExpression(init.expression)
+    ) {
+      return
+    }
+    const call = init.expression
+    if (!isWorkflowDoCall(call, childContext.checker)) {
+      return
+    }
+    const varName = ts.isIdentifier(decl.name) ? decl.name.text : undefined
+    const step = extractRpcStep(call, childContext, varName)
+    if (!step) {
+      return
+    }
+    if (varName) {
+      const type = childContext.checker.getTypeAtLocation(decl)
+      childContext.outputVars.set(varName, { type, node: decl })
+      if (isArrayType(type, childContext.checker)) {
+        childContext.arrayVars.add(varName)
+      }
+    }
+    body.push(step)
+    return
+  }
+
+  if (ts.isExpressionStatement(stmt) || ts.isReturnStatement(stmt)) {
+    const expr = ts.isReturnStatement(stmt) ? stmt.expression : stmt.expression
+    if (!expr) {
+      return
+    }
+    const call = ts.isAwaitExpression(expr)
+      ? ts.isCallExpression(expr.expression)
+        ? expr.expression
+        : null
+      : ts.isCallExpression(expr)
+        ? expr
+        : null
+    if (!call) {
+      return
+    }
+    if (isWorkflowSleepCall(call, childContext.checker)) {
+      const sleepStep = extractSleepStep(call, childContext)
+      if (sleepStep && sleepStep.type === 'sleep') {
+        body.push(sleepStep)
+      }
+      return
+    }
+    if (isWorkflowSuspendCall(call, childContext.checker)) {
+      const suspendStep = extractSuspendStep(call, childContext)
+      if (suspendStep && suspendStep.type === 'suspend') {
+        body.push(suspendStep)
+      }
+      return
+    }
+    if (!isWorkflowDoCall(call, childContext.checker)) {
+      return
+    }
+    const step = extractRpcStep(call, childContext)
+    if (step) {
+      body.push(step)
+    }
+  }
+}
+
 /**
  * Extract parallel fanout from Promise.all(array.map(...))
  */
@@ -1075,66 +1318,49 @@ function extractParallelFanout(
 
   const itemVar = itemParam.name.text
 
-  // Extract workflow.do call from map body
-  let doCall: ts.CallExpression | null = null
-
-  if (ts.isCallExpression(mapFn.body)) {
-    doCall = mapFn.body
-  } else if (ts.isAwaitExpression(mapFn.body)) {
-    // Handle: async (email) => await workflow.do(...)
-    if (ts.isCallExpression(mapFn.body.expression)) {
-      doCall = mapFn.body.expression
-    }
-  } else if (ts.isBlock(mapFn.body)) {
-    // Look for workflow.do in block
-    for (const stmt of mapFn.body.statements) {
-      if (ts.isExpressionStatement(stmt)) {
-        // Handle: await workflow.do(...)
-        if (
-          ts.isAwaitExpression(stmt.expression) &&
-          ts.isCallExpression(stmt.expression.expression)
-        ) {
-          doCall = stmt.expression.expression
-          break
-        }
-      } else if (ts.isReturnStatement(stmt) && stmt.expression) {
-        if (ts.isCallExpression(stmt.expression)) {
-          doCall = stmt.expression
-          break
-        } else if (ts.isAwaitExpression(stmt.expression)) {
-          // Handle: return await workflow.do(...)
-          if (ts.isCallExpression(stmt.expression.expression)) {
-            doCall = stmt.expression.expression
-            break
-          }
-        }
-      }
-    }
-  }
-
-  if (!doCall || !isWorkflowDoCall(doCall, context.checker)) {
-    return null
-  }
-
-  // Create a temporary context for the child step with the loop variable
+  // Create a temporary context for the child steps with the loop variable
   const childContext: ExtractionContext = {
     ...context,
     outputVars: new Map(context.outputVars),
+    arrayVars: new Set(context.arrayVars),
     loopVars: new Set([...context.loopVars, itemVar]),
   }
 
-  const childStep = extractRpcStep(doCall, childContext)
-  if (!childStep) {
+  const body: FanoutStepMeta['body'] = []
+
+  if (ts.isBlock(mapFn.body)) {
+    for (const stmt of mapFn.body.statements) {
+      extractFanoutBodyStep(stmt, childContext, body)
+    }
+  } else {
+    // Concise body: (item) => workflow.do(...) / async (item) => await workflow.do(...)
+    const expr = mapFn.body
+    const doCall = ts.isAwaitExpression(expr)
+      ? ts.isCallExpression(expr.expression)
+        ? expr.expression
+        : null
+      : ts.isCallExpression(expr)
+        ? expr
+        : null
+
+    if (doCall && isWorkflowDoCall(doCall, context.checker)) {
+      const step = extractRpcStep(doCall, childContext)
+      if (step) {
+        body.push(step)
+      }
+    }
+  }
+
+  if (body.length === 0) {
     return null
   }
 
   return {
     type: 'fanout',
-    stepName: childStep.stepName,
     sourceVar,
     itemVar,
     mode: 'parallel',
-    child: childStep,
+    body,
   }
 }
 
@@ -1189,65 +1415,34 @@ function extractSequentialFanout(
 
   const { itemVar, sourceVar } = vars
 
-  // Extract child step and optional sleep from loop body
-  if (!ts.isBlock(statement.statement)) {
-    return null
-  }
+  // Extract child steps and optional sleep from the loop body. A brace-less
+  // body (`for (const x of xs) await workflow.do(...)`) is a single statement
+  // rather than a block, and must still be extracted.
+  const bodyStatements = ts.isBlock(statement.statement)
+    ? statement.statement.statements
+    : [statement.statement]
 
-  let childStep: RpcStepMeta | null = null
+  const body: FanoutStepMeta['body'] = []
   let timeBetween: string | undefined = undefined
 
   // Create a child context with the loop variable added
   const childContext: ExtractionContext = {
     ...context,
     outputVars: new Map(context.outputVars),
+    arrayVars: new Set(context.arrayVars),
     loopVars: new Set([...context.loopVars, itemVar]),
   }
 
-  let workflowDoCount = 0
-
-  for (const stmt of statement.statement.statements) {
-    // Look for workflow.do in VariableStatement (const x = await workflow.do(...))
-    if (ts.isVariableStatement(stmt)) {
-      const declList = stmt.declarationList
-      if (declList.declarations.length === 1) {
-        const decl = declList.declarations[0]
-        const init = decl.initializer
-        if (
-          init &&
-          ts.isAwaitExpression(init) &&
-          ts.isCallExpression(init.expression)
-        ) {
-          const call = init.expression
-          if (isWorkflowDoCall(call, context.checker)) {
-            workflowDoCount++
-            const varName = ts.isIdentifier(decl.name)
-              ? decl.name.text
-              : undefined
-            const step = extractRpcStep(call, childContext, varName)
-            if (step) {
-              childStep = step
-            }
-          }
-        }
-      }
-    }
+  for (const stmt of bodyStatements) {
+    extractFanoutBodyStep(stmt, childContext, body)
 
-    // Look for workflow.do in ExpressionStatement (await workflow.do(...))
+    // Look for workflow.sleep in ExpressionStatement
     if (ts.isExpressionStatement(stmt)) {
       const expr = stmt.expression
 
       if (ts.isAwaitExpression(expr) && ts.isCallExpression(expr.expression)) {
         const call = expr.expression
 
-        if (isWorkflowDoCall(call, context.checker)) {
-          workflowDoCount++
-          const step = extractRpcStep(call, childContext)
-          if (step) {
-            childStep = step
-          }
-        }
-
         if (isWorkflowSleepCall(call, context.checker)) {
           // Extract duration for timeBetween
           const args = call.arguments
@@ -1305,26 +1500,16 @@ function extractSequentialFanout(
     }
   }
 
-  if (!childStep) {
-    return null
-  }
-
-  // If there are multiple workflow.do calls, the loop is too complex for DSL
-  if (workflowDoCount > 1) {
-    context.errors.push({
-      message: `For-of loop has ${workflowDoCount} workflow.do calls but DSL only supports 1. Use pikkuWorkflowComplexFunc for complex loops.`,
-      node: statement,
-    })
+  if (body.length === 0) {
     return null
   }
 
   return {
     type: 'fanout',
-    stepName: childStep.stepName,
     sourceVar,
     itemVar,
     mode: 'sequential',
-    child: childStep,
+    body,
     timeBetween,
   }
 }
@@ -1427,11 +1612,21 @@ function extractReturn(
     }
   }
 
+  // `return r` returns every field of r — record it as a spread of one.
+  if (ts.isIdentifier(statement.expression)) {
+    const varName = statement.expression.text
+    if (context.outputVars.has(varName) || context.contextVars.has(varName)) {
+      return { type: 'return', outputs: {}, spread: [varName] }
+    }
+    return null
+  }
+
   if (!ts.isObjectLiteralExpression(statement.expression)) {
     return null
   }
 
   const outputs: Record<string, OutputBinding> = {}
+  const spread: string[] = []
 
   for (const prop of statement.expression.properties) {
     if (
@@ -1462,16 +1657,22 @@ function extractReturn(
       if (binding) {
         outputs[propName] = binding
       }
+    } else if (
+      ts.isSpreadAssignment(prop) &&
+      ts.isIdentifier(prop.expression)
+    ) {
+      spread.push(prop.expression.text)
     }
   }
 
-  if (Object.keys(outputs).length === 0) {
+  if (Object.keys(outputs).length === 0 && spread.length === 0) {
     return null
   }
 
   return {
     type: 'return',
     outputs,
+    ...(spread.length > 0 ? { spread } : {}),
   }
 }
 
@@ -1586,6 +1787,11 @@ function extractInputSource(
         return { from: 'input', path: propName }
       }
 
+      // A field of the fanout item: users.map((u) => do(..., { id: u.id }))
+      if (context.loopVars.has(objName)) {
+        return { from: 'item', path: propName }
+      }
+
       if (context.outputVars.has(objName)) {
         return { from: 'outputVar', name: objName, path: propName }
       }

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

@@ -115,6 +115,24 @@ export function isWorkflowSuspendCall(
   )
 }
 
+/**
+ * Check if a call expression is workflow.approval()
+ */
+export function isWorkflowApprovalCall(
+  node: ts.CallExpression,
+  _checker: ts.TypeChecker
+): boolean {
+  if (!ts.isPropertyAccessExpression(node.expression)) {
+    return false
+  }
+
+  const propAccess = node.expression
+  return (
+    propAccess.name.text === 'approval' &&
+    isWorkflowWireIdentifier(propAccess.expression)
+  )
+}
+
 /**
  * Check if a throw statement throws WorkflowCancelledException
  * Matches: throw new WorkflowCancelledException(...) or throw WorkflowCancelledException(...)