@pikku/inspector 0.12.33 → 0.12.34

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+## 0.12.34
+
+### Patch Changes
+
+- 92bd643: User flows in the console: workflow graph extraction now captures
+  `workflow.expectEventually` steps and per-step actor names (`{ actor:
+actors.x }`), workflow meta carries `actors`/`title` into the serialized
+  graph, the CLI emits `user-flow-actors.gen.json` for the new
+  `MetaService.getUserFlowActorsMeta()`, and the console Workflows page gains a
+  Workflows / User Flows / Personas toggle. Also fixes complex-workflow graphs
+  being clobbered by a duplicate basic-extraction pass after successful DSL
+  extraction.
+- Updated dependencies [35a9bab]
+- Updated dependencies [92bd643]
+  - @pikku/core@0.12.50
+
 ## 0.12.33
 
 ### Patch Changes

package/dist/add/add-workflow.js

@@ -5,7 +5,7 @@ import { ErrorCode } from '../error-codes.js';
 import { extractStringLiteral, isStringLike, isFunctionLike, extractDescription, extractDuration, } from '../utils/extract-node-value.js';
 import { getCommonWireMetaData, getPropertyValue, } from '../utils/get-property-value.js';
 import { extractDSLWorkflow } from '../utils/workflow/dsl/extract-dsl-workflow.js';
-import { getSourceText } from '../utils/workflow/dsl/patterns.js';
+import { getSourceText, extractActorFromOptions, } from '../utils/workflow/dsl/patterns.js';
 /**
  * Extract a workflow step's display name without letting a non-static name
  * (e.g. a function call) abort the scan. The step name is cosmetic, so a
@@ -86,14 +86,18 @@ export function collectInvokedRPCs(steps, rpcs) {
     }
 }
 /**
- * Scan for workflow.do(), workflow.sleep(), and workflow.cancel() calls to extract workflow steps
+ * Scan for workflow.do(), workflow.expectEventually(), workflow.sleep(), and
+ * workflow.cancel() calls to extract workflow steps
  */
 function getWorkflowInvocations(node, checker, state, workflowName, steps) {
     // Look for property access expressions: workflow.do or workflow.sleep
     if (ts.isPropertyAccessExpression(node)) {
         const { name } = node;
         // Check if this is accessing 'do' or 'sleep' property
-        if (name.text === 'do' || name.text === 'sleep' || name.text === 'cancel') {
+        if (name.text === 'do' ||
+            name.text === 'sleep' ||
+            name.text === 'cancel' ||
+            name.text === 'expectEventually') {
             // Check if the parent is a call expression
             const parent = node.parent;
             if (ts.isCallExpression(parent) && parent.expression === node) {
@@ -113,6 +117,7 @@ function getWorkflowInvocations(node, checker, state, workflowName, steps) {
                             type: 'rpc',
                             stepName,
                             rpcName,
+                            actor: extractActorFromOptions(optionsArg),
                         });
                         state.rpc.invokedFunctions.add(rpcName);
                     }
@@ -125,6 +130,21 @@ function getWorkflowInvocations(node, checker, state, workflowName, steps) {
                         });
                     }
                 }
+                else if (name.text === 'expectEventually' && args.length >= 4) {
+                    // workflow.expectEventually(stepName, rpcName, data, predicate, options?)
+                    const stepName = extractStepName(args[0], checker);
+                    if (isStringLike(args[1], checker)) {
+                        const rpcName = extractStringLiteral(args[1], checker);
+                        steps.push({
+                            type: 'rpc',
+                            stepName,
+                            rpcName,
+                            expectEventually: true,
+                            actor: extractActorFromOptions(args.length >= 5 ? args[4] : undefined),
+                        });
+                        state.rpc.invokedFunctions.add(rpcName);
+                    }
+                }
                 else if (name.text === 'sleep' && args.length >= 2) {
                     // workflow.sleep(stepName, duration)
                     const stepNameArg = args[0];
@@ -282,9 +302,19 @@ export const addWorkflow = (logger, node, checker, state) => {
     // For pikkuWorkflowComplexFunc, also run basic extraction so RPCs in
     // patterns the DSL extractor doesn't handle (array+push, nested Promise.all
     // with identifier args, etc.) are still registered as invoked functions.
+    // When DSL extraction already produced steps this pass is registration-only:
+    // appending to `steps` would duplicate nodes and clobber the graph.
     if (wrapperType !== 'dsl') {
-        getWorkflowInvocations(resolvedFunc, checker, state, workflowName, steps);
+        const sink = steps.length > 0 ? [] : steps;
+        getWorkflowInvocations(resolvedFunc, checker, state, workflowName, sink);
     }
+    // Actor names the flow's steps run as (user flows) — powers the console
+    // personas view and the User Flow graph badges.
+    const actorNames = [
+        ...new Set(steps
+            .map((s) => ('actor' in s ? s.actor : undefined))
+            .filter((a) => typeof a === 'string')),
+    ];
     state.workflows.meta[workflowName] = {
         pikkuFuncId,
         name: workflowName,
@@ -298,6 +328,7 @@ export const addWorkflow = (logger, node, checker, state) => {
         tags,
         expose,
         userFlow: wrapperType === 'user-flow' ? true : undefined,
+        actors: actorNames.length > 0 ? actorNames : undefined,
     };
     // User flows are pure stories of remote RPCs (same rule as client-side CLI
     // renderers): the func may only destructure logger/config — everything else

package/dist/utils/workflow/dsl/extract-dsl-workflow.js

@@ -1,5 +1,5 @@
 import * as ts from 'typescript';
-import { isWorkflowDoCall, isWorkflowSleepCall, isWorkflowSuspendCall, isThrowCancelException, extractCancelReason, isParallelFanout, isParallelGroup, isSequentialFanout, isArrayFilter, isArraySome, isArrayEvery, extractForOfVariable, isArrayType, getSourceText, extractSourcePath, } from './patterns.js';
+import { isWorkflowDoCall, isWorkflowExpectEventuallyCall, extractActorFromOptions, isWorkflowSleepCall, isWorkflowSuspendCall, isThrowCancelException, extractCancelReason, isParallelFanout, isParallelGroup, isSequentialFanout, isArrayFilter, isArraySome, isArrayEvery, extractForOfVariable, isArrayType, getSourceText, extractSourcePath, } from './patterns.js';
 import { validateNoDisallowedPatterns, validateAwaitedCalls, formatValidationErrors, } from './validation.js';
 import { extractStringLiteral, extractNumberLiteral, } from '../../extract-node-value.js';
 /**
@@ -386,9 +386,12 @@ function extractRpcStep(call, context, outputVar) {
         const rpcName = extractStringLiteral(args[1], context.checker);
         // Extract inputs from third argument
         const inputs = args.length >= 3 ? extractInputSources(args[2], context) : undefined;
-        // Extract options from fourth argument
-        const options = args.length >= 4 && ts.isObjectLiteralExpression(args[3])
-            ? extractStepOptions(args[3], context)
+        // do(step, rpc, data, options?) vs expectEventually(step, rpc, data, predicate, options?)
+        const expectEventually = isWorkflowExpectEventuallyCall(call);
+        const optionsIndex = expectEventually ? 4 : 3;
+        const optionsArg = args.length > optionsIndex ? args[optionsIndex] : undefined;
+        const options = optionsArg && ts.isObjectLiteralExpression(optionsArg)
+            ? extractStepOptions(optionsArg, context)
             : undefined;
         return {
             type: 'rpc',
@@ -397,6 +400,8 @@ function extractRpcStep(call, context, outputVar) {
             outputVar,
             inputs,
             options,
+            actor: extractActorFromOptions(optionsArg),
+            expectEventually: expectEventually || undefined,
         };
     }
     catch (error) {

package/dist/utils/workflow/dsl/patterns.d.ts

@@ -3,9 +3,20 @@ import * as ts from 'typescript';
  * Pattern detection helpers for DSL workflow extraction
  */
 /**
- * Check if a call expression is workflow.do()
+ * Check if a call expression is workflow.do() or workflow.expectEventually()
+ * (both are RPC steps; expectEventually is the polling variant used by user flows)
  */
 export declare function isWorkflowDoCall(node: ts.CallExpression, checker: ts.TypeChecker): boolean;
+/**
+ * Check if a call expression is workflow.expectEventually()
+ */
+export declare function isWorkflowExpectEventuallyCall(node: ts.CallExpression): boolean;
+/**
+ * Extract the actor NAME from a step options object literal:
+ * `{ actor: actors.x }` → 'x' (also `actors['x']`). Undefined when absent
+ * or not statically resolvable.
+ */
+export declare function extractActorFromOptions(optionsArg: ts.Expression | undefined): string | undefined;
 /**
  * Check if a call expression is workflow.sleep()
  */

package/dist/utils/workflow/dsl/patterns.js

@@ -3,17 +3,52 @@ import * as ts from 'typescript';
  * Pattern detection helpers for DSL workflow extraction
  */
 /**
- * Check if a call expression is workflow.do()
+ * Check if a call expression is workflow.do() or workflow.expectEventually()
+ * (both are RPC steps; expectEventually is the polling variant used by user flows)
  */
 export function isWorkflowDoCall(node, checker) {
     if (!ts.isPropertyAccessExpression(node.expression)) {
         return false;
     }
     const propAccess = node.expression;
-    return (propAccess.name.text === 'do' &&
+    return ((propAccess.name.text === 'do' ||
+        propAccess.name.text === 'expectEventually') &&
         ts.isIdentifier(propAccess.expression) &&
         propAccess.expression.text === 'workflow');
 }
+/**
+ * Check if a call expression is workflow.expectEventually()
+ */
+export function isWorkflowExpectEventuallyCall(node) {
+    return (ts.isPropertyAccessExpression(node.expression) &&
+        node.expression.name.text === 'expectEventually' &&
+        ts.isIdentifier(node.expression.expression) &&
+        node.expression.expression.text === 'workflow');
+}
+/**
+ * Extract the actor NAME from a step options object literal:
+ * `{ actor: actors.x }` → 'x' (also `actors['x']`). Undefined when absent
+ * or not statically resolvable.
+ */
+export function extractActorFromOptions(optionsArg) {
+    if (!optionsArg || !ts.isObjectLiteralExpression(optionsArg))
+        return;
+    for (const prop of optionsArg.properties) {
+        if (ts.isPropertyAssignment(prop) &&
+            ts.isIdentifier(prop.name) &&
+            prop.name.text === 'actor') {
+            const init = prop.initializer;
+            if (ts.isPropertyAccessExpression(init)) {
+                return init.name.text;
+            }
+            if (ts.isElementAccessExpression(init) &&
+                ts.isStringLiteral(init.argumentExpression)) {
+                return init.argumentExpression.text;
+            }
+        }
+    }
+    return;
+}
 /**
  * Check if a call expression is workflow.sleep()
  */

package/dist/utils/workflow/graph/convert-dsl-to-graph.js

@@ -58,6 +58,12 @@ function convertStepToNode(step, index, steps, nodeIdPrefix = 'step') {
                 rpcName: step.rpcName,
                 next: nextNodeId,
             };
+            if (step.actor) {
+                node.actor = step.actor;
+            }
+            if (step.expectEventually) {
+                node.expectEventually = true;
+            }
             if (step.inputs) {
                 if (step.inputs === 'passthrough') {
                     // Entire data is passed through - store as reference to trigger
@@ -304,8 +310,10 @@ export function convertDslToGraph(workflowName, meta) {
         name: workflowName,
         pikkuFuncId: meta.pikkuFuncId,
         source,
+        title: meta.title,
         description: meta.description,
         tags: meta.tags,
+        actors: meta.actors,
         context: meta.context,
         nodes: nodesRecord,
         entryNodeIds,

package/dist/utils/workflow/graph/workflow-graph.types.d.ts

@@ -96,6 +96,10 @@ export interface FunctionNode extends BaseNode {
     outputVar?: string;
     /** Hash of nodeId + RPC input/output schemas for version detection */
     stepHash?: string;
+    /** User-flow actor name this step runs as (workflow.do {actor: actors.x}) */
+    actor?: string;
+    /** True for workflow.expectEventually polling steps (user flows) */
+    expectEventually?: boolean;
 }
 /**
  * Flow node - control flow only, no RPC call
@@ -136,10 +140,14 @@ export interface SerializedWorkflowGraph {
     pikkuFuncId: string;
     /** Source type: 'dsl' for pikkuWorkflowFunc, 'graph' for pikkuWorkflowGraph */
     source: WorkflowSourceType;
+    /** Optional short display name */
+    title?: string;
     /** Optional description */
     description?: string;
     /** Tags for organization */
     tags?: string[];
+    /** Actor names a user flow's steps run as */
+    actors?: string[];
     /** If true, workflow always executes inline without queues */
     inline?: boolean;
     /** Workflow context/state variables (from Zod schema) */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/inspector",
-  "version": "0.12.33",
+  "version": "0.12.34",
   "author": "yasser.fadl@gmail.com",
   "license": "BUSL-1.1",
   "type": "module",
@@ -35,7 +35,7 @@
   },
   "dependencies": {
     "@openapi-contrib/json-schema-to-openapi-schema": "^4.3.1",
-    "@pikku/core": "^0.12.49",
+    "@pikku/core": "^0.12.50",
     "openapi-types": "^12.1.3",
     "path-to-regexp": "^8.3.0",
     "ts-json-schema-generator": "2.9.1-next.16",

package/src/add/add-workflow.ts

@@ -16,7 +16,10 @@ import {
   getPropertyValue,
 } from '../utils/get-property-value.js'
 import { extractDSLWorkflow } from '../utils/workflow/dsl/extract-dsl-workflow.js'
-import { getSourceText } from '../utils/workflow/dsl/patterns.js'
+import {
+  getSourceText,
+  extractActorFromOptions,
+} from '../utils/workflow/dsl/patterns.js'
 
 /**
  * Extract a workflow step's display name without letting a non-static name
@@ -86,7 +89,8 @@ export function collectInvokedRPCs(
 }
 
 /**
- * Scan for workflow.do(), workflow.sleep(), and workflow.cancel() calls to extract workflow steps
+ * Scan for workflow.do(), workflow.expectEventually(), workflow.sleep(), and
+ * workflow.cancel() calls to extract workflow steps
  */
 function getWorkflowInvocations(
   node: ts.Node,
@@ -100,7 +104,12 @@ function getWorkflowInvocations(
     const { name } = node
 
     // Check if this is accessing 'do' or 'sleep' property
-    if (name.text === 'do' || name.text === 'sleep' || name.text === 'cancel') {
+    if (
+      name.text === 'do' ||
+      name.text === 'sleep' ||
+      name.text === 'cancel' ||
+      name.text === 'expectEventually'
+    ) {
       // Check if the parent is a call expression
       const parent = node.parent
       if (ts.isCallExpression(parent) && parent.expression === node) {
@@ -125,6 +134,7 @@ function getWorkflowInvocations(
               type: 'rpc',
               stepName,
               rpcName,
+              actor: extractActorFromOptions(optionsArg),
             })
             state.rpc.invokedFunctions.add(rpcName)
           } else if (isFunctionLike(secondArg)) {
@@ -135,6 +145,20 @@ function getWorkflowInvocations(
               description: description || '<dynamic>',
             })
           }
+        } else if (name.text === 'expectEventually' && args.length >= 4) {
+          // workflow.expectEventually(stepName, rpcName, data, predicate, options?)
+          const stepName = extractStepName(args[0], checker)
+          if (isStringLike(args[1], checker)) {
+            const rpcName = extractStringLiteral(args[1], checker)
+            steps.push({
+              type: 'rpc',
+              stepName,
+              rpcName,
+              expectEventually: true,
+              actor: extractActorFromOptions(args.length >= 5 ? args[4] : undefined),
+            })
+            state.rpc.invokedFunctions.add(rpcName)
+          }
         } else if (name.text === 'sleep' && args.length >= 2) {
           // workflow.sleep(stepName, duration)
           const stepNameArg = args[0]
@@ -337,10 +361,23 @@ export const addWorkflow: AddWiring = (logger, node, checker, state) => {
   // For pikkuWorkflowComplexFunc, also run basic extraction so RPCs in
   // patterns the DSL extractor doesn't handle (array+push, nested Promise.all
   // with identifier args, etc.) are still registered as invoked functions.
+  // When DSL extraction already produced steps this pass is registration-only:
+  // appending to `steps` would duplicate nodes and clobber the graph.
   if (wrapperType !== 'dsl') {
-    getWorkflowInvocations(resolvedFunc, checker, state, workflowName, steps)
+    const sink: WorkflowStepMeta[] = steps.length > 0 ? [] : steps
+    getWorkflowInvocations(resolvedFunc, checker, state, workflowName, sink)
   }
 
+  // Actor names the flow's steps run as (user flows) — powers the console
+  // personas view and the User Flow graph badges.
+  const actorNames = [
+    ...new Set(
+      steps
+        .map((s) => ('actor' in s ? s.actor : undefined))
+        .filter((a): a is string => typeof a === 'string')
+    ),
+  ]
+
   state.workflows.meta[workflowName] = {
     pikkuFuncId,
     name: workflowName,
@@ -354,6 +391,7 @@ export const addWorkflow: AddWiring = (logger, node, checker, state) => {
     tags,
     expose,
     userFlow: wrapperType === 'user-flow' ? true : undefined,
+    actors: actorNames.length > 0 ? actorNames : undefined,
   }
 
   // User flows are pure stories of remote RPCs (same rule as client-side CLI

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

@@ -21,6 +21,8 @@ import type {
 } from '@pikku/core/workflow'
 import {
   isWorkflowDoCall,
+  isWorkflowExpectEventuallyCall,
+  extractActorFromOptions,
   isWorkflowSleepCall,
   isWorkflowSuspendCall,
   isThrowCancelException,
@@ -553,10 +555,15 @@ function extractRpcStep(
     const inputs =
       args.length >= 3 ? extractInputSources(args[2], context) : undefined
 
-    // Extract options from fourth argument
+    // do(step, rpc, data, options?) vs expectEventually(step, rpc, data, predicate, options?)
+    const expectEventually = isWorkflowExpectEventuallyCall(call)
+    const optionsIndex = expectEventually ? 4 : 3
+    const optionsArg =
+      args.length > optionsIndex ? args[optionsIndex] : undefined
+
     const options =
-      args.length >= 4 && ts.isObjectLiteralExpression(args[3])
-        ? extractStepOptions(args[3], context)
+      optionsArg && ts.isObjectLiteralExpression(optionsArg)
+        ? extractStepOptions(optionsArg, context)
         : undefined
 
     return {
@@ -566,6 +573,8 @@ function extractRpcStep(
       outputVar,
       inputs,
       options,
+      actor: extractActorFromOptions(optionsArg),
+      expectEventually: expectEventually || undefined,
     }
   } catch (error) {
     context.errors.push({

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

@@ -5,7 +5,8 @@ import * as ts from 'typescript'
  */
 
 /**
- * Check if a call expression is workflow.do()
+ * Check if a call expression is workflow.do() or workflow.expectEventually()
+ * (both are RPC steps; expectEventually is the polling variant used by user flows)
  */
 export function isWorkflowDoCall(
   node: ts.CallExpression,
@@ -17,12 +18,57 @@ export function isWorkflowDoCall(
 
   const propAccess = node.expression
   return (
-    propAccess.name.text === 'do' &&
+    (propAccess.name.text === 'do' ||
+      propAccess.name.text === 'expectEventually') &&
     ts.isIdentifier(propAccess.expression) &&
     propAccess.expression.text === 'workflow'
   )
 }
 
+/**
+ * Check if a call expression is workflow.expectEventually()
+ */
+export function isWorkflowExpectEventuallyCall(
+  node: ts.CallExpression
+): boolean {
+  return (
+    ts.isPropertyAccessExpression(node.expression) &&
+    node.expression.name.text === 'expectEventually' &&
+    ts.isIdentifier(node.expression.expression) &&
+    node.expression.expression.text === 'workflow'
+  )
+}
+
+/**
+ * Extract the actor NAME from a step options object literal:
+ * `{ actor: actors.x }` → 'x' (also `actors['x']`). Undefined when absent
+ * or not statically resolvable.
+ */
+export function extractActorFromOptions(
+  optionsArg: ts.Expression | undefined
+): string | undefined {
+  if (!optionsArg || !ts.isObjectLiteralExpression(optionsArg)) return
+  for (const prop of optionsArg.properties) {
+    if (
+      ts.isPropertyAssignment(prop) &&
+      ts.isIdentifier(prop.name) &&
+      prop.name.text === 'actor'
+    ) {
+      const init = prop.initializer
+      if (ts.isPropertyAccessExpression(init)) {
+        return init.name.text
+      }
+      if (
+        ts.isElementAccessExpression(init) &&
+        ts.isStringLiteral(init.argumentExpression)
+      ) {
+        return init.argumentExpression.text
+      }
+    }
+  }
+  return
+}
+
 /**
  * Check if a call expression is workflow.sleep()
  */

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

@@ -93,6 +93,12 @@ function convertStepToNode(
         rpcName: step.rpcName,
         next: nextNodeId,
       }
+      if (step.actor) {
+        node.actor = step.actor
+      }
+      if (step.expectEventually) {
+        node.expectEventually = true
+      }
       if (step.inputs) {
         if (step.inputs === 'passthrough') {
           // Entire data is passed through - store as reference to trigger
@@ -403,8 +409,10 @@ export function convertDslToGraph(
     name: workflowName,
     pikkuFuncId: meta.pikkuFuncId,
     source,
+    title: meta.title,
     description: meta.description,
     tags: meta.tags,
+    actors: meta.actors,
     context: meta.context,
     nodes: nodesRecord,
     entryNodeIds,

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

@@ -142,6 +142,10 @@ export interface FunctionNode extends BaseNode {
   outputVar?: string
   /** Hash of nodeId + RPC input/output schemas for version detection */
   stepHash?: string
+  /** User-flow actor name this step runs as (workflow.do {actor: actors.x}) */
+  actor?: string
+  /** True for workflow.expectEventually polling steps (user flows) */
+  expectEventually?: boolean
 }
 
 /**
@@ -191,10 +195,14 @@ export interface SerializedWorkflowGraph {
   pikkuFuncId: string
   /** Source type: 'dsl' for pikkuWorkflowFunc, 'graph' for pikkuWorkflowGraph */
   source: WorkflowSourceType
+  /** Optional short display name */
+  title?: string
   /** Optional description */
   description?: string
   /** Tags for organization */
   tags?: string[]
+  /** Actor names a user flow's steps run as */
+  actors?: string[]
   /** If true, workflow always executes inline without queues */
   inline?: boolean
   /** Workflow context/state variables (from Zod schema) */