@pikku/inspector 0.12.43 → 0.12.45

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

@@ -197,11 +197,15 @@ function extractStep(statement, context) {
 function extractVariableDeclaration(statement, context) {
     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;
     const init = decl.initializer;
@@ -295,6 +299,55 @@ function extractVariableDeclaration(statement, context) {
     }
     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, decl, context) {
+    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.name;
+                    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)
  */
@@ -327,11 +380,11 @@ function extractExpressionStatement(statement, context) {
                             value: literalValue,
                         };
                     }
-                    // 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),
                     };
                 }
             }
@@ -490,6 +543,17 @@ function extractStepOptions(optionsNode, context) {
                     // 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(prop.initializer, context.checker);
@@ -518,7 +582,20 @@ function extractSleepStep(call, context) {
             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 {
             type: 'sleep',
@@ -835,6 +912,84 @@ function extractArrayPredicate(call, context, outputVar) {
         outputVar,
     };
 }
+/**
+ * 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, childContext, body) {
+    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(...))
  */
@@ -863,63 +1018,45 @@ function extractParallelFanout(call, context) {
         return null;
     }
     const itemVar = itemParam.name.text;
-    // Extract workflow.do call from map body
-    let doCall = 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 = {
         ...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 = [];
+    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,
     };
 }
 /**
@@ -959,55 +1096,28 @@ function extractSequentialFanout(statement, context) {
         return null;
     }
     const { itemVar, sourceVar } = vars;
-    // Extract child step and optional sleep from loop body
-    if (!ts.isBlock(statement.statement)) {
-        return null;
-    }
-    let childStep = 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];
+    const body = [];
     let timeBetween = undefined;
     // Create a child context with the loop variable added
     const childContext = {
         ...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;
-                        }
-                    }
-                }
-            }
-        }
-        // Look for workflow.do in ExpressionStatement (await workflow.do(...))
+    for (const stmt of bodyStatements) {
+        extractFanoutBodyStep(stmt, childContext, body);
+        // 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;
@@ -1060,24 +1170,15 @@ function extractSequentialFanout(statement, context) {
             }
         }
     }
-    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,
     };
 }
@@ -1163,10 +1264,19 @@ function extractReturn(statement, context) {
             return extractSleepStep(call, context);
         }
     }
+    // `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 = {};
+    const spread = [];
     for (const prop of statement.expression.properties) {
         if (ts.isPropertyAssignment(prop) ||
             ts.isShorthandPropertyAssignment(prop)) {
@@ -1195,13 +1305,18 @@ function extractReturn(statement, context) {
                 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 } : {}),
     };
 }
 /**
@@ -1297,6 +1412,10 @@ function extractInputSource(node, context) {
             if (objName === context.inputParamName) {
                 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/dist/utils/workflow/graph/convert-dsl-to-graph.js

@@ -56,6 +56,7 @@ function convertStepToNode(step, index, steps, nodeIdPrefix = 'step') {
             const node = {
                 nodeId,
                 rpcName: step.rpcName,
+                stepName: step.stepName,
                 next: nextNodeId,
             };
             if (step.actor) {
@@ -82,16 +83,45 @@ function convertStepToNode(step, index, steps, nodeIdPrefix = 'step') {
             if (step.options) {
                 node.options = {
                     retries: step.options.retries,
-                    retryDelay: step.options.retryDelay?.toString(),
+                    retryDelay: step.options.retryDelay,
                 };
             }
+            // An onError handler is written as an rpc name, but the graph routes to
+            // node ids — materialise a node for it so the console has something to
+            // draw the error edge to, exactly as in a hand-authored graph.
+            if (step.options?.onError) {
+                const handlerId = `${nodeId}_onError`;
+                node.onError = handlerId;
+                return [
+                    node,
+                    {
+                        nodeId: handlerId,
+                        rpcName: step.options.onError,
+                        stepName: `${step.stepName} (on error)`,
+                    },
+                ];
+            }
             return [node];
         }
         case 'sleep': {
             const node = {
                 nodeId,
                 flow: 'sleep',
+                stepName: step.stepName,
                 duration: step.duration,
+                expression: step.expression,
+                next: nextNodeId,
+            };
+            return [node];
+        }
+        case 'suspend': {
+            // A suspend yields no value, but it must still be a node: the previous
+            // step's `next` points at it, so omitting it dead-ends traversal and
+            // silently deletes every step that follows.
+            const node = {
+                nodeId,
+                flow: 'suspend',
+                reason: step.reason,
                 next: nextNodeId,
             };
             return [node];
@@ -160,13 +190,28 @@ function convertStepToNode(step, index, steps, nodeIdPrefix = 'step') {
         case 'switch': {
             const caseNodes = [];
             const cases = [];
+            // A case with no statements falls through to the next one. Dropping it
+            // would lose the value entirely, so it is held until an entry exists.
+            let fallingThrough = [];
             for (let i = 0; i < step.cases.length; i++) {
                 const caseSteps = convertStepsToNodes(step.cases[i].steps, `${nodeId}_case${i}`);
-                if (caseSteps.length > 0) {
+                if (caseSteps.length === 0) {
+                    fallingThrough.push({
+                        value: step.cases[i].value,
+                        expression: step.cases[i].expression,
+                    });
+                    continue;
+                }
+                {
+                    const entry = caseSteps[0].nodeId;
+                    for (const pending of fallingThrough) {
+                        cases.push({ ...pending, entry });
+                    }
+                    fallingThrough = [];
                     cases.push({
                         value: step.cases[i].value,
                         expression: step.cases[i].expression,
-                        entry: caseSteps[0].nodeId,
+                        entry,
                     });
                     // Link last case node to next (unless terminal flow)
                     if (nextNodeId) {
@@ -191,6 +236,13 @@ function convertStepToNode(step, index, steps, nodeIdPrefix = 'step') {
                     caseNodes.push(...defaultNodes);
                 }
             }
+            // Cases falling through past the last one land in default, or exit.
+            const trailingEntry = defaultEntry ?? nextNodeId;
+            if (trailingEntry) {
+                for (const pending of fallingThrough) {
+                    cases.push({ ...pending, entry: trailingEntry });
+                }
+            }
             const node = {
                 nodeId,
                 flow: 'switch',
@@ -221,8 +273,11 @@ function convertStepToNode(step, index, steps, nodeIdPrefix = 'step') {
             return [node, ...childNodes];
         }
         case 'fanout': {
-            // Convert child step
-            const childNodes = convertStepToNode(step.child, 0, [step.child], `${nodeId}_item`);
+            // Convert the per-iteration body into a `next`-chained sequence
+            const childNodes = [];
+            for (let i = 0; i < step.body.length; i++) {
+                childNodes.push(...convertStepToNode(step.body[i], i, step.body, `${nodeId}_item`));
+            }
             const node = {
                 nodeId,
                 flow: 'fanout',
@@ -265,6 +320,7 @@ function convertStepToNode(step, index, steps, nodeIdPrefix = 'step') {
                 nodeId,
                 flow: 'return',
                 outputs: step.outputs,
+                spread: step.spread,
             };
             return [node];
         }
@@ -282,6 +338,7 @@ function convertStepToNode(step, index, steps, nodeIdPrefix = 'step') {
                 flow: 'set',
                 variable: step.variable,
                 value: step.value,
+                expression: step.expression,
                 next: nextNodeId,
             };
             return [node];

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

@@ -58,15 +58,15 @@ export type SerializedNext = string | string[] | {
 export interface NodeOptions {
     /** Number of retry attempts on failure */
     retries?: number;
-    /** Delay between retries (e.g., '1s', '5s') */
-    retryDelay?: string;
+    /** Delay between retries (e.g., '1s', '5s', or a number of milliseconds) */
+    retryDelay?: string | number;
     /** Timeout for node execution (e.g., '30s', '5m') */
     timeout?: string;
 }
 /**
  * Flow node types for control flow (no RPC call)
  */
-export type FlowType = 'sleep' | 'approval' | 'branch' | 'parallel' | 'fanout' | 'inline' | 'switch' | 'filter' | 'arrayPredicate' | 'return' | 'cancel' | 'set';
+export type FlowType = 'sleep' | 'suspend' | 'approval' | 'branch' | 'parallel' | 'fanout' | 'inline' | 'switch' | 'filter' | 'arrayPredicate' | 'return' | 'cancel' | 'set';
 import type { ContextVariable, WorkflowContext, WorkflowPlannedStep } from '@pikku/core/workflow';
 export type { ContextVariable, WorkflowContext };
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/inspector",
-  "version": "0.12.43",
+  "version": "0.12.45",
   "author": "yasser.fadl@gmail.com",
   "license": "BUSL-1.1",
   "type": "module",
@@ -44,10 +44,10 @@
     "zod-to-ts": "^2.1.0"
   },
   "peerDependencies": {
-    "@pikku/core": "^0.12.64"
+    "@pikku/core": "^0.12.67"
   },
   "devDependencies": {
-    "@pikku/core": "^0.12.64",
+    "@pikku/core": "^0.12.67",
     "@types/node": "^24.11.0"
   },
   "engines": {

package/run-tests.sh

@@ -38,7 +38,7 @@ if [ ${#files[@]} -eq 0 ]; then
 fi
 
 # Construct the node command
-node_cmd=(node --import tsx --test)
+node_cmd=(node --import tsx --expose-gc --test)
 
 # Append options based on flags
 if [ "$watch_mode" = true ]; then

package/src/add/add-auth.test.ts

@@ -190,11 +190,11 @@ describe('addAuth inspector', () => {
       [
         "import { pikkuBetterAuth } from '@pikku/better-auth'",
         "import { betterAuth } from 'better-auth'",
-        "import { bearer, admin, twoFactor } from 'better-auth/plugins'",
+        "import { bearer, apiKey, twoFactor } from 'better-auth/plugins'",
         'export const auth = pikkuBetterAuth(() =>',
         '  betterAuth({',
         "    socialProviders: { github: { clientId: 'x', clientSecret: 'y' } },",
-        '    plugins: [bearer(), admin(), twoFactor({ issuer: "pikku" })],',
+        '    plugins: [bearer(), apiKey(), twoFactor({ issuer: "pikku" })],',
         '  })',
         ')',
       ].join('\n')
@@ -204,10 +204,10 @@ describe('addAuth inspector', () => {
     try {
       const state = await inspect(makeLogger(criticals), [file], { rootDir })
       assert.equal(criticals.length, 0)
-      assert.deepEqual(state.auth.plugins, ['bearer', 'admin', 'twoFactor'])
+      assert.deepEqual(state.auth.plugins, ['bearer', 'apiKey', 'twoFactor'])
       assert.deepEqual(state.auth.definition?.plugins, [
         'bearer',
-        'admin',
+        'apiKey',
         'twoFactor',
       ])
     } finally {

package/src/add/add-credential.ts

@@ -45,6 +45,7 @@ export const addCredential: AddWiring = (
       | string
       | null
     const typeValue = getPropertyValue(obj, 'type') as string | null
+    const docsUrlValue = getPropertyValue(obj, 'docsUrl') as string | null
 
     if (!nameValue) {
       logger.critical(
@@ -179,6 +180,7 @@ export const addCredential: AddWiring = (
       displayName: displayNameValue,
       description: descriptionValue || undefined,
       type: typeValue as 'singleton' | 'wire',
+      docsUrl: docsUrlValue || undefined,
       schema: schemaLookupName,
       oauth2,
       sourceFile,

package/src/add/add-keyed-wiring.ts

@@ -56,6 +56,7 @@ export const createAddKeyedWiring = (config: KeyedWiringConfig): AddWiring => {
       const rotationPeriodValue = getPropertyValue(obj, 'rotationPeriod') as
         | string
         | null
+      const docsUrlValue = getPropertyValue(obj, 'docsUrl') as string | null
       const idValue = getPropertyValue(obj, config.idField) as string | null
 
       let schemaVariableName: string | null = null
@@ -165,6 +166,7 @@ export const createAddKeyedWiring = (config: KeyedWiringConfig): AddWiring => {
         displayName: displayNameValue,
         description: descriptionValue || undefined,
         rotationPeriod: rotationPeriodValue || undefined,
+        docsUrl: docsUrlValue || undefined,
         [config.idField]: idValue,
         schema: schemaLookupName,
         sourceFile,