@pikku/inspector 0.11.1 → 0.11.2

package/src/add/add-workflow.ts

@@ -3,7 +3,7 @@ import { AddWiring, InspectorState } from '../types.js'
 import { extractFunctionName } from '../utils/extract-function-name.js'
 import { extractFunctionNode } from '../utils/extract-function-node.js'
 import { ErrorCode } from '../error-codes.js'
-import { WorkflowStepMeta } from '@pikku/core/workflow'
+import { WorkflowStepMeta, WorkflowContext } from '@pikku/core/workflow'
 import {
   extractStringLiteral,
   isStringLike,
@@ -11,8 +11,62 @@ import {
   extractDescription,
   extractDuration,
 } from '../utils/extract-node-value.js'
-import { extractSimpleWorkflow } from '../workflow/extract-simple-workflow.js'
 import { getCommonWireMetaData } from '../utils/get-property-value.js'
+import { extractDSLWorkflow } from '../utils/workflow/dsl/extract-dsl-workflow.js'
+
+/**
+ * Recursively check if any step has inline type (non-serializable)
+ */
+function hasInlineSteps(steps: WorkflowStepMeta[]): boolean {
+  for (const step of steps) {
+    if (step.type === 'inline') {
+      return true
+    } else if (step.type === 'branch') {
+      for (const branch of step.branches) {
+        if (hasInlineSteps(branch.steps)) return true
+      }
+      if (step.elseSteps && hasInlineSteps(step.elseSteps)) return true
+    } else if (step.type === 'switch' && step.cases) {
+      for (const c of step.cases) {
+        if (c.steps && hasInlineSteps(c.steps)) return true
+      }
+      if (step.defaultSteps && hasInlineSteps(step.defaultSteps)) return true
+    } else if (step.type === 'fanout' && step.child) {
+      if (hasInlineSteps([step.child])) return true
+    } else if (step.type === 'parallel' && step.children) {
+      if (hasInlineSteps(step.children)) return true
+    }
+  }
+  return false
+}
+
+/**
+ * Recursively collect all RPC names from workflow steps
+ */
+function collectInvokedRPCs(
+  steps: WorkflowStepMeta[],
+  rpcs: Set<string>
+): void {
+  for (const step of steps) {
+    if (step.type === 'rpc' && step.rpcName) {
+      rpcs.add(step.rpcName)
+    } else if (step.type === 'branch') {
+      for (const branch of step.branches) {
+        collectInvokedRPCs(branch.steps, rpcs)
+      }
+      if (step.elseSteps) collectInvokedRPCs(step.elseSteps, rpcs)
+    } else if (step.type === 'switch' && step.cases) {
+      for (const c of step.cases) {
+        if (c.steps) collectInvokedRPCs(c.steps, rpcs)
+      }
+      if (step.defaultSteps) collectInvokedRPCs(step.defaultSteps, rpcs)
+    } else if (step.type === 'fanout' && step.child) {
+      collectInvokedRPCs([step.child], rpcs)
+    } else if (step.type === 'parallel' && step.children) {
+      collectInvokedRPCs(step.children, rpcs)
+    }
+  }
+}
 
 /**
  * Scan for workflow.do(), workflow.sleep(), and workflow.cancel() calls to extract workflow steps
@@ -87,13 +141,10 @@ function getWorkflowInvocations(
     }
   }
 
-  // Don't recurse into nested functions - only look at top-level workflow calls
+  // Recurse into children, including arrow functions (for Promise.all callbacks)
+  // but skip function declarations (which would be separate functions)
   ts.forEachChild(node, (child) => {
-    if (
-      ts.isFunctionDeclaration(child) ||
-      ts.isFunctionExpression(child) ||
-      ts.isArrowFunction(child)
-    ) {
+    if (ts.isFunctionDeclaration(child)) {
       return
     }
     getWorkflowInvocations(child, checker, state, workflowName, steps)
@@ -117,11 +168,11 @@ export const addWorkflow: AddWiring = (logger, node, checker, state) => {
     return
   }
 
-  let wrapperType: 'simple' | 'regular' | null = null
+  let wrapperType: 'dsl' | 'regular' | null = null
   if (expression.text === 'pikkuWorkflowFunc') {
+    wrapperType = 'dsl'
+  } else if (expression.text === 'pikkuWorkflowComplexFunc') {
     wrapperType = 'regular'
-  } else if (expression.text === 'pikkuSimpleWorkflowFunc') {
-    wrapperType = 'simple'
   } else {
     return
   }
@@ -198,41 +249,76 @@ export const addWorkflow: AddWiring = (logger, node, checker, state) => {
   }
 
   let steps: WorkflowStepMeta[] = []
-  let simple: boolean | undefined = undefined
+  let context: WorkflowContext | undefined = undefined
+  let dsl: boolean | undefined = undefined
 
-  // Try simple workflow extraction first
+  // Try DSL workflow extraction first
   // Pass the whole CallExpression node so findWorkflowFunction can find the arrow function
-  const result = extractSimpleWorkflow(node, checker)
+  const result = extractDSLWorkflow(node, checker)
 
   if (result.status === 'ok' && result.steps) {
-    // Simple extraction succeeded
+    // Extraction succeeded
     steps = result.steps
-    simple = true
+    context = result.context
+
+    // Check if workflow contains inline steps (non-serializable)
+    if (hasInlineSteps(steps)) {
+      if (wrapperType === 'dsl') {
+        // pikkuWorkflowFunc should not have inline steps
+        logger.critical(
+          ErrorCode.INVALID_DSL_WORKFLOW,
+          `Workflow '${workflowName}' uses pikkuWorkflowFunc but contains inline steps which are not allowed in DSL workflows. Use pikkuWorkflowComplexFunc instead.`
+        )
+        return
+      }
+      // pikkuWorkflowComplexFunc with inline steps is marked as non-dsl
+      dsl = false
+    } else {
+      // pikkuWorkflowComplexFunc is always non-dsl, pikkuWorkflowFunc is dsl
+      dsl = wrapperType === 'dsl'
+    }
+
+    // Collect all invoked RPCs from workflow steps
+    const rpcs = new Set<string>()
+    collectInvokedRPCs(steps, rpcs)
+    for (const rpc of rpcs) {
+      state.rpc.invokedFunctions.add(rpc)
+    }
   } else {
-    // Simple extraction failed
-    if (wrapperType === 'simple') {
-      // For pikkuSimpleWorkflowFunc, this is a critical error
+    // DSL extraction failed
+    if (wrapperType === 'dsl') {
+      // For pikkuWorkflowFunc, this is a critical error
+      // But still track RPC invocations for function registration
+      getWorkflowInvocations(resolvedFunc, checker, state, workflowName, steps)
       logger.critical(
-        ErrorCode.INVALID_SIMPLE_WORKFLOW,
-        `Workflow '${workflowName}' uses pikkuSimpleWorkflowFunc but does not conform to simple workflow DSL:\n${result.reason || 'Unknown error'}`
+        ErrorCode.INVALID_DSL_WORKFLOW,
+        `Workflow '${workflowName}' uses pikkuWorkflowFunc but does not conform to DSL workflow rules:\n${result.reason || 'Unknown error'}`
       )
       return
     } else {
-      // For pikkuWorkflowFunc, fall back to basic extraction
+      // For pikkuWorkflowComplexFunc, fall back to basic extraction
       logger.debug(
-        `Workflow '${workflowName}' could not be extracted as simple workflow: ${result.reason || 'Unknown error'}. Falling back to basic extraction.`
+        `Workflow '${workflowName}' could not be extracted as DSL workflow: ${result.reason || 'Unknown error'}. Falling back to basic extraction.`
       )
-      simple = false
+      dsl = false
     }
   }
 
-  getWorkflowInvocations(resolvedFunc, checker, state, workflowName, steps)
+  /**
+   * For non-dsl workflows or pikkuWorkflowComplexFunc, run basic extraction
+   * to ensure all RPC invocations are tracked for function registration.
+   * This catches RPCs in Promise.all callbacks and other patterns DSL can't extract.
+   */
+  if (!dsl || wrapperType === 'regular') {
+    getWorkflowInvocations(resolvedFunc, checker, state, workflowName, steps)
+  }
 
   state.workflows.meta[workflowName] = {
     pikkuFuncName,
     workflowName,
     steps,
-    simple,
+    context,
+    dsl,
     summary,
     description,
     errors,

package/src/error-codes.ts

@@ -11,6 +11,7 @@ export enum ErrorCode {
   // Validation errors
   MISSING_NAME = 'PKU111',
   MISSING_DESCRIPTION = 'PKU123',
+  INVALID_VALUE = 'PKU124',
   MISSING_URI = 'PKU220',
   MISSING_FUNC = 'PKU236',
   INVALID_TAGS_TYPE = 'PKU247',
@@ -21,7 +22,7 @@ export enum ErrorCode {
   CLI_CLIENTSIDE_RENDERER_HAS_SERVICES = 'PKU672',
   DYNAMIC_STEP_NAME = 'PKU529',
   WORKFLOW_ORCHESTRATOR_NOT_CONFIGURED = 'PKU600',
-  INVALID_SIMPLE_WORKFLOW = 'PKU641',
+  INVALID_DSL_WORKFLOW = 'PKU641',
 
   // Configuration errors
   CONFIG_TYPE_NOT_FOUND = 'PKU426',
@@ -29,6 +30,7 @@ export enum ErrorCode {
   SCHEMA_NO_ROOT = 'PKU431',
   SCHEMA_GENERATION_ERROR = 'PKU456',
   SCHEMA_LOAD_ERROR = 'PKU488',
+  INLINE_ZOD_SCHEMA = 'PKU489',
 
   // Function errors
   FUNCTION_METADATA_NOT_FOUND = 'PKU559',

package/src/index.ts

@@ -16,3 +16,13 @@ export type { SerializableInspectorState } from './utils/serialize-inspector-sta
 export { filterInspectorState } from './utils/filter-inspector-state.js'
 export { writeAllServiceMetadata } from './utils/write-service-metadata.js'
 export type { ServiceMetadata } from './utils/extract-service-metadata.js'
+export {
+  convertAllDslToGraphs,
+  convertDslToGraph,
+} from './utils/workflow/graph/convert-dsl-to-graph.js'
+export {
+  deserializeDslWorkflow,
+  deserializeGraphWorkflow,
+  deserializeAllDslWorkflows,
+} from './utils/workflow/dsl/deserialize-dsl-workflow.js'
+export type { SerializedWorkflowGraph } from './utils/workflow/graph/workflow-graph.types.js'

package/src/inspector.ts

@@ -29,6 +29,7 @@ export function getInitialInspectorState(rootDir: string): InspectorState {
     filesAndMethods: {},
     filesAndMethodsErrors: new Map(),
     typesLookup: new Map(),
+    zodLookup: new Map(),
     functions: {
       typesMap: new TypesMap(),
       meta: {},
@@ -64,6 +65,8 @@ export function getInitialInspectorState(rootDir: string): InspectorState {
     workflows: {
       meta: {},
       files: new Map(),
+      graphMeta: {},
+      graphFiles: new Map(),
     },
     rpc: {
       internalMeta: {},
@@ -71,6 +74,7 @@ export function getInitialInspectorState(rootDir: string): InspectorState {
       exposedMeta: {},
       exposedFiles: new Map(),
       invokedFunctions: new Set(),
+      usedExternalPackages: new Set(),
     },
     mcpEndpoints: {
       resourcesMeta: {},
@@ -85,6 +89,14 @@ export function getInitialInspectorState(rootDir: string): InspectorState {
       },
       files: new Set(),
     },
+    forgeNodes: {
+      meta: {},
+      files: new Set(),
+    },
+    forgeCredentials: {
+      meta: {},
+      files: new Set(),
+    },
     middleware: {
       meta: {},
       tagMiddleware: new Map(),
@@ -131,15 +143,19 @@ export const inspect = (
     `Got type checker in ${(performance.now() - startChecker).toFixed(2)}ms`
   )
 
+  // Use provided rootDir or infer from source files
+  const rootDir = options.rootDir || findCommonAncestor(routeFiles)
+
   const startSourceFiles = performance.now()
-  const sourceFiles = program.getSourceFiles()
+  // Filter source files to only include files within the project rootDir
+  // This prevents picking up types from external packages (including workspace symlinks)
+  const sourceFiles = program
+    .getSourceFiles()
+    .filter((sf) => sf.fileName.startsWith(rootDir))
   logger.debug(
     `Got source files in ${(performance.now() - startSourceFiles).toFixed(2)}ms`
   )
 
-  // Infer root directory from source files
-  const rootDir = findCommonAncestor(routeFiles)
-
   const state = getInitialInspectorState(rootDir)
 
   // First sweep: add all functions

package/src/types.ts

@@ -6,9 +6,11 @@ import { QueueWorkersMeta } from '@pikku/core/queue'
 import { WorkflowsMeta } from '@pikku/core/workflow'
 import { MCPResourceMeta, MCPToolMeta, MCPPromptMeta } from '@pikku/core/mcp'
 import { CLIMeta } from '@pikku/core/cli'
+import { ForgeNodesMeta, ForgeCredentialsMeta } from '@pikku/core/forge-node'
 import { TypesMap } from './types-map.js'
 import { FunctionsMeta, FunctionServicesMeta } from '@pikku/core'
 import { ErrorCode } from './error-codes.js'
+import type { SerializedWorkflowGraphs } from './utils/workflow/graph/workflow-graph.types.js'
 
 export type PathToNameAndType = Map<
   string,
@@ -56,6 +58,14 @@ export interface InspectorHTTPState {
   routePermissions: Map<string, PermissionGroupMeta>
 }
 
+/**
+ * Zod schema reference for deferred conversion to JSON Schema at build time
+ */
+export interface ZodSchemaRef {
+  variableName: string
+  sourceFile: string
+}
+
 export interface InspectorFunctionState {
   typesMap: TypesMap
   meta: FunctionsMeta
@@ -116,6 +126,8 @@ export type InspectorFilters = {
 
 export type InspectorOptions = Partial<{
   setupOnly: boolean
+  /** Project root directory - used to filter out external package files */
+  rootDir: string
   types: Partial<{
     configFileType: string
     userSessionType: string
@@ -198,6 +210,7 @@ export interface InspectorState {
   filesAndMethods: InspectorFilesAndMethods
   filesAndMethodsErrors: Map<string, PathToNameAndType>
   typesLookup: Map<string, ts.Type[]> // Lookup for types by name (e.g., function input types, Config type)
+  zodLookup: Map<string, ZodSchemaRef> // Lookup for Zod schemas by name for deferred JSON Schema conversion
   http: InspectorHTTPState
   functions: InspectorFunctionState
   channels: InspectorChannelState
@@ -212,13 +225,16 @@ export interface InspectorState {
   workflows: {
     meta: WorkflowsMeta
     files: Map<string, { path: string; exportedName: string }>
+    graphMeta: SerializedWorkflowGraphs
+    graphFiles: Map<string, { path: string; exportedName: string }>
   }
   rpc: {
     internalMeta: Record<string, string>
     internalFiles: Map<string, { path: string; exportedName: string }>
     exposedMeta: Record<string, string>
     exposedFiles: Map<string, { path: string; exportedName: string }>
-    invokedFunctions: Set<string> // Track functions called via rpc.invoke()
+    invokedFunctions: Set<string>
+    usedExternalPackages: Set<string>
   }
   mcpEndpoints: {
     resourcesMeta: MCPResourceMeta
@@ -230,6 +246,14 @@ export interface InspectorState {
     meta: CLIMeta
     files: Set<string>
   }
+  forgeNodes: {
+    meta: ForgeNodesMeta
+    files: Set<string>
+  }
+  forgeCredentials: {
+    meta: ForgeCredentialsMeta
+    files: Set<string>
+  }
   middleware: InspectorMiddlewareState
   permissions: InspectorPermissionState
   serviceAggregation: {

package/src/utils/extract-function-name.ts

@@ -360,10 +360,10 @@ export function extractFunctionName(
           if (
             ts.isPropertyAssignment(prop) &&
             ts.isIdentifier(prop.name) &&
-            prop.name.text === 'name' &&
+            prop.name.text === 'override' &&
             ts.isStringLiteral(prop.initializer)
           ) {
-            // Priority 1: Object with name property
+            // Priority 1: Object with override property
             result.explicitName = prop.initializer.text
             break
           }
@@ -614,17 +614,17 @@ export function extractFunctionName(
             // instead of the variable declaration position
             originalCallExpr = decl.initializer
 
-            // Check for object with 'name' property in first argument
+            // Check for object with 'override' property in first argument
             const firstArg = decl.initializer.arguments[0]
             if (firstArg && ts.isObjectLiteralExpression(firstArg)) {
               for (const prop of firstArg.properties) {
                 if (
                   ts.isPropertyAssignment(prop) &&
                   ts.isIdentifier(prop.name) &&
-                  prop.name.text === 'name' &&
+                  prop.name.text === 'override' &&
                   ts.isStringLiteral(prop.initializer)
                 ) {
-                  // Priority 1: Object with name property
+                  // Priority 1: Object with override property
                   result.explicitName = prop.initializer.text
                   break
                 }
@@ -713,7 +713,7 @@ export function extractFunctionName(
   ) {
     result.propertyName = parent.name.text
   }
-  // 3) Handle any remaining cases for pikkuFunc({ name: '…', func: … })
+  // 3) Handle any remaining cases for pikkuFunc({ override: '…', func: … })
   else if (ts.isCallExpression(originalCallExpr)) {
     const firstArg = originalCallExpr.arguments[0]
     if (firstArg && ts.isObjectLiteralExpression(firstArg)) {
@@ -721,7 +721,7 @@ export function extractFunctionName(
         if (
           ts.isPropertyAssignment(prop) &&
           ts.isIdentifier(prop.name) &&
-          prop.name.text === 'name' &&
+          prop.name.text === 'override' &&
           ts.isStringLiteral(prop.initializer) &&
           !result.explicitName // Only set if not already set
         ) {

package/src/utils/get-property-value.ts

@@ -57,7 +57,7 @@ export const getPropertyValue = (
 }
 
 /**
- * Extracts common wire metadata (tags, summary, description, errors) directly from an object
+ * Extracts common wire metadata (title, tags, summary, description, errors) directly from an object
  * @param obj - The TypeScript object literal expression to extract metadata from
  * @param wiringType - The type of wiring (e.g., 'HTTP route', 'Channel', 'Queue worker')
  * @param wiringName - The name/identifier of the wiring (e.g., route path, channel name)
@@ -70,12 +70,14 @@ export const getCommonWireMetaData = (
   wiringName: string | null,
   logger?: { critical: (code: ErrorCode, message: string) => void }
 ): {
+  title?: string
   tags?: string[]
   summary?: string
   description?: string
   errors?: string[]
 } => {
   const metadata: {
+    title?: string
     tags?: string[]
     summary?: string
     description?: string
@@ -86,7 +88,12 @@ export const getCommonWireMetaData = (
     if (ts.isPropertyAssignment(prop) && ts.isIdentifier(prop.name)) {
       const propName = prop.name.text
 
-      if (propName === 'summary' && ts.isStringLiteral(prop.initializer)) {
+      if (propName === 'title' && ts.isStringLiteral(prop.initializer)) {
+        metadata.title = prop.initializer.text
+      } else if (
+        propName === 'summary' &&
+        ts.isStringLiteral(prop.initializer)
+      ) {
         metadata.summary = prop.initializer.text
       } else if (
         propName === 'description' &&

package/src/utils/serialize-inspector-state.ts

@@ -62,6 +62,7 @@ export interface SerializableInspectorState {
       >,
     ]
   >
+  zodLookup: Array<[string, { variableName: string; sourceFile: string }]>
   functions: {
     typesMap: {
       map: Array<[string, { originalName: string; path: string | null }]>
@@ -115,6 +116,8 @@ export interface SerializableInspectorState {
   workflows: {
     meta: InspectorState['workflows']['meta']
     files: Array<[string, { path: string; exportedName: string }]>
+    graphMeta: InspectorState['workflows']['graphMeta']
+    graphFiles: Array<[string, { path: string; exportedName: string }]>
   }
   rpc: {
     internalMeta: InspectorState['rpc']['internalMeta']
@@ -122,6 +125,7 @@ export interface SerializableInspectorState {
     exposedMeta: InspectorState['rpc']['exposedMeta']
     exposedFiles: Array<[string, { path: string; exportedName: string }]>
     invokedFunctions: string[]
+    usedExternalPackages: string[]
   }
   mcpEndpoints: {
     resourcesMeta: InspectorState['mcpEndpoints']['resourcesMeta']
@@ -133,6 +137,14 @@ export interface SerializableInspectorState {
     meta: InspectorState['cli']['meta']
     files: string[]
   }
+  forgeNodes: {
+    meta: InspectorState['forgeNodes']['meta']
+    files: string[]
+  }
+  forgeCredentials: {
+    meta: InspectorState['forgeCredentials']['meta']
+    files: string[]
+  }
   middleware: {
     meta: InspectorState['middleware']['meta']
     tagMiddleware: Array<
@@ -231,6 +243,7 @@ export function serializeInspectorState(
     filesAndMethodsErrors: Array.from(
       state.filesAndMethodsErrors.entries()
     ).map(([key, mapValue]) => [key, Array.from(mapValue.entries())] as const),
+    zodLookup: Array.from(state.zodLookup.entries()),
     functions: {
       typesMap: serializeTypesMap(state.functions.typesMap),
       meta: state.functions.meta,
@@ -258,6 +271,8 @@ export function serializeInspectorState(
     workflows: {
       meta: state.workflows.meta,
       files: Array.from(state.workflows.files.entries()),
+      graphMeta: state.workflows.graphMeta,
+      graphFiles: Array.from(state.workflows.graphFiles.entries()),
     },
     rpc: {
       internalMeta: state.rpc.internalMeta,
@@ -265,6 +280,7 @@ export function serializeInspectorState(
       exposedMeta: state.rpc.exposedMeta,
       exposedFiles: Array.from(state.rpc.exposedFiles.entries()),
       invokedFunctions: Array.from(state.rpc.invokedFunctions),
+      usedExternalPackages: Array.from(state.rpc.usedExternalPackages),
     },
     mcpEndpoints: {
       resourcesMeta: state.mcpEndpoints.resourcesMeta,
@@ -276,6 +292,14 @@ export function serializeInspectorState(
       meta: state.cli.meta,
       files: Array.from(state.cli.files),
     },
+    forgeNodes: {
+      meta: state.forgeNodes.meta,
+      files: Array.from(state.forgeNodes.files),
+    },
+    forgeCredentials: {
+      meta: state.forgeCredentials.meta,
+      files: Array.from(state.forgeCredentials.files),
+    },
     middleware: {
       meta: state.middleware.meta,
       tagMiddleware: Array.from(state.middleware.tagMiddleware.entries()),
@@ -302,7 +326,9 @@ export function serializeInspectorState(
  */
 export function deserializeInspectorState(
   data: SerializableInspectorState
-): Omit<InspectorState, 'typesLookup'> {
+): Omit<InspectorState, 'typesLookup' | 'zodLookup'> & {
+  zodLookup: Map<string, { variableName: string; sourceFile: string }>
+} {
   // Helper to deserialize TypesMap
   const deserializeTypesMap = (
     serialized: SerializableInspectorState['functions']['typesMap']
@@ -337,6 +363,7 @@ export function deserializeInspectorState(
         new Map(entries),
       ])
     ),
+    zodLookup: new Map(data.zodLookup || []),
     functions: {
       typesMap: deserializeTypesMap(data.functions.typesMap),
       meta: data.functions.meta,
@@ -364,6 +391,8 @@ export function deserializeInspectorState(
     workflows: {
       meta: data.workflows.meta,
       files: new Map(data.workflows.files),
+      graphMeta: data.workflows.graphMeta || {},
+      graphFiles: new Map(data.workflows.graphFiles || []),
     },
     rpc: {
       internalMeta: data.rpc.internalMeta,
@@ -371,6 +400,7 @@ export function deserializeInspectorState(
       exposedMeta: data.rpc.exposedMeta,
       exposedFiles: new Map(data.rpc.exposedFiles),
       invokedFunctions: new Set(data.rpc.invokedFunctions),
+      usedExternalPackages: new Set(data.rpc.usedExternalPackages || []),
     },
     mcpEndpoints: {
       resourcesMeta: data.mcpEndpoints.resourcesMeta,
@@ -382,6 +412,14 @@ export function deserializeInspectorState(
       meta: data.cli.meta,
       files: new Set(data.cli.files),
     },
+    forgeNodes: {
+      meta: data.forgeNodes?.meta || {},
+      files: new Set(data.forgeNodes?.files || []),
+    },
+    forgeCredentials: {
+      meta: data.forgeCredentials?.meta || {},
+      files: new Set(data.forgeCredentials?.files || []),
+    },
     middleware: {
       meta: data.middleware.meta,
       tagMiddleware: new Map(data.middleware.tagMiddleware),