@pikku/inspector 0.12.31 → 0.12.33

package/CHANGELOG.md

@@ -1,3 +1,39 @@
+## 0.12.33
+
+### Patch Changes
+
+- 4c17f7e: user flows: actors move onto the workflow wire + `pikku userflow` command
+  - Actors are no longer a singleton service: `startWorkflow(..., { actors })`
+    registers them per run and they arrive on the wire —
+    `func: async ({ logger }, input, { workflow, actors })`.
+  - Inspector enforces user flows are pure remote stories (PKU673): a
+    pikkuUserFlow func may only destructure `logger`/`config` from services.
+  - New `pikku userflow run <environment> [--flows a,b] [--tags x,y]` runs flows
+    against `userFlows.environments` from pikku.config.json (secret from
+    USER_FLOW_ACTOR_SECRET env), refusing internal (non-actor) steps so runs
+    against staging/production never touch local services; non-zero exit on
+    failure. `pikku userflow list` prints names, descriptions and tags.
+  - Workflow meta now carries `title` (parity with HTTP routes/functions).
+
+- Updated dependencies [4c17f7e]
+  - @pikku/core@0.12.49
+
+## 0.12.32
+
+### Patch Changes
+
+- 8dfddc3: pikkuUserFlow: user flows as workflows. A complex workflow whose steps can run
+  as actors over the real transport — `workflow.do(step, rpc, data, { actor:
+actors.yasser })` — plus `workflow.expectEventually(...)` for polling async
+  effects. Actor steps never queue and never dispatch internally, so auth
+  middleware/permissions are exercised end-to-end; flows double as e2e tests and
+  staged/production health checks. Ships UserFlowActor types +
+  createHttpUserFlowActors (lazy sign-in via `/auth/sign-in/actor` with a
+  server-held secret), inspector source `'user-flow'`, and a console badge.
+- Updated dependencies [5f2c566]
+- Updated dependencies [8dfddc3]
+  - @pikku/core@0.12.48
+
 ## 0.12.31
 
 ### Patch Changes

package/dist/add/add-functions.js

@@ -250,9 +250,11 @@ export const addFunctions = (logger, node, checker, state, options) => {
     if (!ts.isIdentifier(expression)) {
         return;
     }
-    // Match identifiers that contain both "pikku" and "func" (case insensitive)
+    // Match identifiers that contain both "pikku" and "func" (case insensitive),
+    // plus pikkuUserFlow (a workflow wrapper without "func" in its name)
     const pikkuFuncPattern = /pikku.*func/i;
-    if (!pikkuFuncPattern.test(expression.text)) {
+    if (!pikkuFuncPattern.test(expression.text) &&
+        expression.text !== 'pikkuUserFlow') {
         return;
     }
     // only handle calls like pikkuFunc(...)

package/dist/add/add-workflow.d.ts

@@ -5,7 +5,7 @@ import type { WorkflowStepMeta } from '@pikku/core/workflow';
  */
 export declare function collectInvokedRPCs(steps: WorkflowStepMeta[], rpcs: Set<string>): void;
 /**
- * Inspector for pikkuWorkflowFunc() and pikkuWorkflowComplexFunc() calls
- * Detects workflow registration and extracts metadata
+ * Inspector for pikkuWorkflowFunc(), pikkuWorkflowComplexFunc() and
+ * pikkuUserFlow() calls. Detects workflow registration and extracts metadata.
  */
 export declare const addWorkflow: AddWiring;

package/dist/add/add-workflow.js

@@ -156,8 +156,8 @@ function getWorkflowInvocations(node, checker, state, workflowName, steps) {
     });
 }
 /**
- * Inspector for pikkuWorkflowFunc() and pikkuWorkflowComplexFunc() calls
- * Detects workflow registration and extracts metadata
+ * Inspector for pikkuWorkflowFunc(), pikkuWorkflowComplexFunc() and
+ * pikkuUserFlow() calls. Detects workflow registration and extracts metadata.
  */
 export const addWorkflow = (logger, node, checker, state) => {
     if (!ts.isCallExpression(node)) {
@@ -176,6 +176,11 @@ export const addWorkflow = (logger, node, checker, state) => {
     else if (expression.text === 'pikkuWorkflowComplexFunc') {
         wrapperType = 'complex';
     }
+    else if (expression.text === 'pikkuUserFlow') {
+        // A user flow is a complex workflow whose steps run as actors over the
+        // real transport — same extraction rules as complex, distinct meta.
+        wrapperType = 'user-flow';
+    }
     else {
         return;
     }
@@ -193,6 +198,7 @@ export const addWorkflow = (logger, node, checker, state) => {
     const { funcNode, resolvedFunc } = extractFunctionNode(firstArg, checker);
     // Extract metadata if using object form
     let tags;
+    let title;
     let summary;
     let description;
     let errors;
@@ -202,6 +208,7 @@ export const addWorkflow = (logger, node, checker, state) => {
         if (metadata.disabled)
             return;
         tags = metadata.tags;
+        title = metadata.title;
         summary = metadata.summary;
         description = metadata.description;
         errors = metadata.errors;
@@ -230,7 +237,7 @@ export const addWorkflow = (logger, node, checker, state) => {
     // Try DSL workflow extraction first
     // Pass the whole CallExpression node so findWorkflowFunction can find the arrow function
     const result = extractDSLWorkflow(node, checker, {
-        allowInline: wrapperType === 'complex',
+        allowInline: wrapperType !== 'dsl',
     });
     if (result.status === 'ok' && result.steps) {
         // Extraction succeeded
@@ -275,7 +282,7 @@ 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.
-    if (wrapperType === 'complex') {
+    if (wrapperType !== 'dsl') {
         getWorkflowInvocations(resolvedFunc, checker, state, workflowName, steps);
     }
     state.workflows.meta[workflowName] = {
@@ -284,15 +291,31 @@ export const addWorkflow = (logger, node, checker, state) => {
         steps,
         context,
         dsl,
+        title,
         summary,
         description,
         errors,
         tags,
         expose,
+        userFlow: wrapperType === 'user-flow' ? true : 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
+    // must go through actor steps so the flow runs against the TARGET
+    // environment, never local services.
+    const funcMeta = state.functions.meta[pikkuFuncId];
+    if (wrapperType === 'user-flow' && funcMeta?.services) {
+        const disallowed = funcMeta.services.services.filter((svc) => svc !== 'logger' && svc !== 'config');
+        if (disallowed.length > 0) {
+            logger.critical(ErrorCode.USER_FLOW_HAS_SERVICES, `User flow '${workflowName}' destructures services: ${disallowed.join(', ')}. ` +
+                `User flows may only use 'logger'/'config' — drive everything else through ` +
+                `actor steps (workflow.do(step, rpc, data, { actor: actors.x })) so the flow ` +
+                `runs against the target environment.`);
+            return;
+        }
+    }
     // Workflow functions require platform services that aren't visible
     // through parameter destructuring (they're accessed via workflow.do/sleep)
-    const funcMeta = state.functions.meta[pikkuFuncId];
     if (funcMeta?.services) {
         for (const svc of [
             'workflowService',

package/dist/error-codes.d.ts

@@ -19,6 +19,7 @@ export declare enum ErrorCode {
     MISSING_QUEUE_NAME = "PKU384",
     MISSING_CHANNEL_NAME = "PKU400",
     CLI_CLIENTSIDE_RENDERER_HAS_SERVICES = "PKU672",
+    USER_FLOW_HAS_SERVICES = "PKU673",
     DYNAMIC_STEP_NAME = "PKU529",
     WORKFLOW_ORCHESTRATOR_NOT_CONFIGURED = "PKU600",
     INVALID_DSL_WORKFLOW = "PKU641",

package/dist/error-codes.js

@@ -21,6 +21,7 @@ export var ErrorCode;
     ErrorCode["MISSING_QUEUE_NAME"] = "PKU384";
     ErrorCode["MISSING_CHANNEL_NAME"] = "PKU400";
     ErrorCode["CLI_CLIENTSIDE_RENDERER_HAS_SERVICES"] = "PKU672";
+    ErrorCode["USER_FLOW_HAS_SERVICES"] = "PKU673";
     ErrorCode["DYNAMIC_STEP_NAME"] = "PKU529";
     ErrorCode["WORKFLOW_ORCHESTRATOR_NOT_CONFIGURED"] = "PKU600";
     ErrorCode["INVALID_DSL_WORKFLOW"] = "PKU641";

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

@@ -291,10 +291,15 @@ export function convertDslToGraph(workflowName, meta) {
         nodesRecord[node.nodeId] = node;
     }
     const entryNodeIds = nodes.length > 0 ? [nodes[0].nodeId] : [];
-    // Determine source type based on dsl flag:
+    // Determine source type:
+    // - userFlow: complex workflow whose steps run as actors (user flow)
     // - dsl === true: pure DSL workflow, can be serialized
     // - dsl === false: complex workflow with inline steps, not serializable
-    const source = meta.dsl === false ? 'complex' : 'dsl';
+    const source = meta.userFlow
+        ? 'user-flow'
+        : meta.dsl === false
+            ? 'complex'
+            : 'dsl';
     return {
         name: workflowName,
         pikkuFuncId: meta.pikkuFuncId,

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

@@ -123,8 +123,9 @@ export declare const isFlowNode: (node: SerializedGraphNode) => node is FlowNode
  * - 'dsl': Pure DSL workflow (pikkuWorkflowFunc) - can be round-tripped to code
  * - 'complex': Complex workflow (pikkuWorkflowComplexFunc) - contains inline steps, not serializable
  * - 'graph': Graph-based workflow (pikkuWorkflowGraph)
+ * - 'user-flow': User flow (pikkuUserFlow) - complex workflow whose steps run as actors
  */
-export type WorkflowSourceType = 'dsl' | 'complex' | 'graph';
+export type WorkflowSourceType = 'dsl' | 'complex' | 'graph' | 'user-flow';
 /**
  * Serialized workflow graph - the canonical JSON format
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/inspector",
-  "version": "0.12.31",
+  "version": "0.12.33",
   "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.45",
+    "@pikku/core": "^0.12.49",
     "openapi-types": "^12.1.3",
     "path-to-regexp": "^8.3.0",
     "ts-json-schema-generator": "2.9.1-next.16",

package/src/add/add-functions.ts

@@ -357,9 +357,13 @@ export const addFunctions: AddWiring = (
     return
   }
 
-  // Match identifiers that contain both "pikku" and "func" (case insensitive)
+  // Match identifiers that contain both "pikku" and "func" (case insensitive),
+  // plus pikkuUserFlow (a workflow wrapper without "func" in its name)
   const pikkuFuncPattern = /pikku.*func/i
-  if (!pikkuFuncPattern.test(expression.text)) {
+  if (
+    !pikkuFuncPattern.test(expression.text) &&
+    expression.text !== 'pikkuUserFlow'
+  ) {
     return
   }
 

package/src/add/add-workflow.ts

@@ -169,8 +169,8 @@ function getWorkflowInvocations(
 }
 
 /**
- * Inspector for pikkuWorkflowFunc() and pikkuWorkflowComplexFunc() calls
- * Detects workflow registration and extracts metadata
+ * Inspector for pikkuWorkflowFunc(), pikkuWorkflowComplexFunc() and
+ * pikkuUserFlow() calls. Detects workflow registration and extracts metadata.
  */
 export const addWorkflow: AddWiring = (logger, node, checker, state) => {
   if (!ts.isCallExpression(node)) {
@@ -185,11 +185,15 @@ export const addWorkflow: AddWiring = (logger, node, checker, state) => {
     return
   }
 
-  let wrapperType: 'dsl' | 'complex' | null = null
+  let wrapperType: 'dsl' | 'complex' | 'user-flow' | null = null
   if (expression.text === 'pikkuWorkflowFunc') {
     wrapperType = 'dsl'
   } else if (expression.text === 'pikkuWorkflowComplexFunc') {
     wrapperType = 'complex'
+  } else if (expression.text === 'pikkuUserFlow') {
+    // A user flow is a complex workflow whose steps run as actors over the
+    // real transport — same extraction rules as complex, distinct meta.
+    wrapperType = 'user-flow'
   } else {
     return
   }
@@ -220,6 +224,7 @@ export const addWorkflow: AddWiring = (logger, node, checker, state) => {
 
   // Extract metadata if using object form
   let tags: string[] | undefined
+  let title: string | undefined
   let summary: string | undefined
   let description: string | undefined
   let errors: string[] | undefined
@@ -235,6 +240,7 @@ export const addWorkflow: AddWiring = (logger, node, checker, state) => {
     )
     if (metadata.disabled) return
     tags = metadata.tags
+    title = metadata.title
     summary = metadata.summary
     description = metadata.description
     errors = metadata.errors
@@ -277,7 +283,7 @@ export const addWorkflow: AddWiring = (logger, node, checker, state) => {
   // Try DSL workflow extraction first
   // Pass the whole CallExpression node so findWorkflowFunction can find the arrow function
   const result = extractDSLWorkflow(node, checker, {
-    allowInline: wrapperType === 'complex',
+    allowInline: wrapperType !== 'dsl',
   })
 
   if (result.status === 'ok' && result.steps) {
@@ -331,7 +337,7 @@ 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.
-  if (wrapperType === 'complex') {
+  if (wrapperType !== 'dsl') {
     getWorkflowInvocations(resolvedFunc, checker, state, workflowName, steps)
   }
 
@@ -341,16 +347,38 @@ export const addWorkflow: AddWiring = (logger, node, checker, state) => {
     steps,
     context,
     dsl,
+    title,
     summary,
     description,
     errors,
     tags,
     expose,
+    userFlow: wrapperType === 'user-flow' ? true : 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
+  // must go through actor steps so the flow runs against the TARGET
+  // environment, never local services.
+  const funcMeta = state.functions.meta[pikkuFuncId]
+  if (wrapperType === 'user-flow' && funcMeta?.services) {
+    const disallowed = funcMeta.services.services.filter(
+      (svc) => svc !== 'logger' && svc !== 'config'
+    )
+    if (disallowed.length > 0) {
+      logger.critical(
+        ErrorCode.USER_FLOW_HAS_SERVICES,
+        `User flow '${workflowName}' destructures services: ${disallowed.join(', ')}. ` +
+          `User flows may only use 'logger'/'config' — drive everything else through ` +
+          `actor steps (workflow.do(step, rpc, data, { actor: actors.x })) so the flow ` +
+          `runs against the target environment.`
+      )
+      return
+    }
   }
 
   // Workflow functions require platform services that aren't visible
   // through parameter destructuring (they're accessed via workflow.do/sleep)
-  const funcMeta = state.functions.meta[pikkuFuncId]
   if (funcMeta?.services) {
     for (const svc of [
       'workflowService',

package/src/error-codes.ts

@@ -21,6 +21,7 @@ export enum ErrorCode {
   MISSING_QUEUE_NAME = 'PKU384',
   MISSING_CHANNEL_NAME = 'PKU400',
   CLI_CLIENTSIDE_RENDERER_HAS_SERVICES = 'PKU672',
+  USER_FLOW_HAS_SERVICES = 'PKU673',
   DYNAMIC_STEP_NAME = 'PKU529',
   WORKFLOW_ORCHESTRATOR_NOT_CONFIGURED = 'PKU600',
   INVALID_DSL_WORKFLOW = 'PKU641',

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

@@ -389,10 +389,15 @@ export function convertDslToGraph(
 
   const entryNodeIds = nodes.length > 0 ? [nodes[0].nodeId] : []
 
-  // Determine source type based on dsl flag:
+  // Determine source type:
+  // - userFlow: complex workflow whose steps run as actors (user flow)
   // - dsl === true: pure DSL workflow, can be serialized
   // - dsl === false: complex workflow with inline steps, not serializable
-  const source = meta.dsl === false ? 'complex' : 'dsl'
+  const source = meta.userFlow
+    ? 'user-flow'
+    : meta.dsl === false
+      ? 'complex'
+      : 'dsl'
 
   return {
     name: workflowName,

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

@@ -177,8 +177,9 @@ export const isFlowNode = (node: SerializedGraphNode): node is FlowNode =>
  * - 'dsl': Pure DSL workflow (pikkuWorkflowFunc) - can be round-tripped to code
  * - 'complex': Complex workflow (pikkuWorkflowComplexFunc) - contains inline steps, not serializable
  * - 'graph': Graph-based workflow (pikkuWorkflowGraph)
+ * - 'user-flow': User flow (pikkuUserFlow) - complex workflow whose steps run as actors
  */
-export type WorkflowSourceType = 'dsl' | 'complex' | 'graph'
+export type WorkflowSourceType = 'dsl' | 'complex' | 'graph' | 'user-flow'
 
 /**
  * Serialized workflow graph - the canonical JSON format