@pikku/inspector 0.10.2 → 0.11.0

package/src/add/add-workflow.ts

@@ -0,0 +1,231 @@
+import * as ts from 'typescript'
+import {
+  getPropertyValue,
+  getPropertyTags,
+} from '../utils/get-property-value.js'
+import { PikkuDocs } from '@pikku/core'
+import { AddWiring, InspectorState } from '../types.js'
+import { extractFunctionName } from '../utils/extract-function-name.js'
+import {
+  getPropertyAssignmentInitializer,
+  resolveFunctionDeclaration,
+} from '../utils/type-utils.js'
+import { resolveMiddleware } from '../utils/middleware.js'
+import { extractWireNames } from '../utils/post-process.js'
+import { ErrorCode } from '../error-codes.js'
+import { WorkflowStepMeta } from '@pikku/core/workflow'
+import {
+  extractStringLiteral,
+  extractNumberLiteral,
+  extractPropertyString,
+  isStringLike,
+  isFunctionLike,
+} from '../utils/extract-node-value.js'
+
+/**
+ * Scan for workflow.do() and workflow.sleep() calls to extract workflow steps
+ */
+function getWorkflowInvocations(
+  node: ts.Node,
+  checker: ts.TypeChecker,
+  state: InspectorState,
+  workflowName: string,
+  steps: WorkflowStepMeta[]
+) {
+  // 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') {
+      // Check if the parent is a call expression
+      const parent = node.parent
+      if (ts.isCallExpression(parent) && parent.expression === node) {
+        const args = parent.arguments
+
+        if (name.text === 'do' && args.length >= 2) {
+          // workflow.do(stepName, rpcName|fn, data?, options?)
+          const stepNameArg = args[0]
+          const secondArg = args[1]
+          const optionsArg =
+            args.length >= 3 ? args[args.length - 1] : undefined
+
+          const stepName = extractStringLiteral(stepNameArg, checker)
+          const description =
+            extractDescription(optionsArg, checker) ?? undefined
+
+          // Determine form by checking 2nd argument type
+          if (isStringLike(secondArg, checker)) {
+            // RPC form: workflow.do(stepName, rpcName, data, options?)
+            const rpcName = extractStringLiteral(secondArg, checker)
+            steps.push({
+              type: 'rpc',
+              stepName,
+              rpcName,
+              description,
+            })
+            state.rpc.invokedFunctions.add(rpcName)
+          } else if (isFunctionLike(secondArg)) {
+            // Inline form: workflow.do(stepName, fn, options?)
+            steps.push({
+              type: 'inline',
+              stepName: stepName || '<dynamic>',
+              description: description || '<dynamic>',
+            })
+          }
+        } else if (name.text === 'sleep' && args.length >= 2) {
+          // workflow.sleep(stepName, duration)
+          const stepNameArg = args[0]
+          const durationArg = args[1]
+
+          const stepName = extractStringLiteral(stepNameArg, checker)
+          const duration = extractDuration(durationArg, checker)
+
+          steps.push({
+            type: 'sleep',
+            stepName: stepName || '<dynamic>',
+            duration: duration || '<dynamic>',
+          })
+        }
+      }
+    }
+  }
+
+  // Don't recurse into nested functions - only look at top-level workflow calls
+  ts.forEachChild(node, (child) => {
+    if (
+      ts.isFunctionDeclaration(child) ||
+      ts.isFunctionExpression(child) ||
+      ts.isArrowFunction(child)
+    ) {
+      return
+    }
+    getWorkflowInvocations(child, checker, state, workflowName, steps)
+  })
+}
+
+/**
+ * Extract description from options object
+ */
+function extractDescription(
+  optionsNode: ts.Node | undefined,
+  checker: ts.TypeChecker
+): string | null {
+  if (!optionsNode || !ts.isObjectLiteralExpression(optionsNode)) {
+    return null
+  }
+  return extractPropertyString(optionsNode, 'description', checker)
+}
+
+/**
+ * Extract duration value (number or string)
+ */
+function extractDuration(
+  node: ts.Node,
+  checker: ts.TypeChecker
+): string | number | null {
+  const numValue = extractNumberLiteral(node)
+  if (numValue !== null) {
+    return numValue
+  }
+  return extractStringLiteral(node, checker)
+}
+
+/**
+ * Inspector for wireWorkflow() calls
+ * Detects workflow registration and extracts metadata
+ */
+export const addWorkflow: AddWiring = (
+  logger,
+  node,
+  checker,
+  state,
+  options
+) => {
+  if (!ts.isCallExpression(node)) {
+    return
+  }
+
+  const args = node.arguments
+  const firstArg = args[0]
+  const expression = node.expression
+
+  // Check if the call is to wireWorkflow
+  if (!ts.isIdentifier(expression) || expression.text !== 'wireWorkflow') {
+    return
+  }
+
+  if (!firstArg) {
+    return
+  }
+
+  if (ts.isObjectLiteralExpression(firstArg)) {
+    const obj = firstArg
+
+    const workflowName = getPropertyValue(obj, 'name') as string | null
+    const description = getPropertyValue(obj, 'description') as
+      | string
+      | undefined
+    const docs = (getPropertyValue(obj, 'docs') as PikkuDocs) || undefined
+    const tags = getPropertyTags(obj, 'Workflow', workflowName, logger)
+
+    // --- find the referenced function ---
+    const funcInitializer = getPropertyAssignmentInitializer(
+      obj,
+      'func',
+      true,
+      checker
+    )
+
+    if (!workflowName) {
+      logger.critical(
+        ErrorCode.MISSING_NAME,
+        `Wasn't able to determine 'name' property for workflow wiring.`
+      )
+      return
+    }
+
+    if (!funcInitializer) {
+      logger.critical(
+        ErrorCode.MISSING_FUNC,
+        `No valid 'func' property for workflow '${workflowName}'.`
+      )
+      return
+    }
+
+    const pikkuFuncName = extractFunctionName(
+      funcInitializer,
+      checker,
+      state.rootDir
+    ).pikkuFuncName
+
+    // --- resolve middleware ---
+    const middleware = resolveMiddleware(state, obj, tags, checker)
+
+    // --- track used functions/middleware for service aggregation ---
+    state.serviceAggregation.usedFunctions.add(pikkuFuncName)
+    extractWireNames(middleware).forEach((name) =>
+      state.serviceAggregation.usedMiddleware.add(name)
+    )
+
+    state.workflows.files.add(node.getSourceFile().fileName)
+
+    // Extract workflow steps from function body
+    // Resolve the identifier to the actual function declaration
+    const resolvedFunc = resolveFunctionDeclaration(funcInitializer, checker)
+    const steps: WorkflowStepMeta[] = []
+    if (resolvedFunc) {
+      getWorkflowInvocations(resolvedFunc, checker, state, workflowName, steps)
+    }
+
+    state.workflows.meta[workflowName] = {
+      pikkuFuncName,
+      workflowName,
+      description,
+      docs,
+      tags,
+      middleware,
+      steps,
+    }
+  }
+}

package/src/error-codes.ts

@@ -19,6 +19,8 @@ export enum ErrorCode {
   MISSING_QUEUE_NAME = 'PKU384',
   MISSING_CHANNEL_NAME = 'PKU400',
   CLI_CLIENTSIDE_RENDERER_HAS_SERVICES = 'PKU672',
+  DYNAMIC_STEP_NAME = 'PKU529',
+  WORKFLOW_ORCHESTRATOR_NOT_CONFIGURED = 'PKU600',
 
   // Configuration errors
   CONFIG_TYPE_NOT_FOUND = 'PKU426',
@@ -40,4 +42,7 @@ export enum ErrorCode {
   PERMISSION_TAG_INVALID = 'PKU836',
   PERMISSION_EMPTY_ARRAY = 'PKU937',
   PERMISSION_PATTERN_INVALID = 'PKU975',
+
+  // Feature Flag
+  WORKFLOW_MULTI_QUEUE_NOT_SUPPORTED = 'PKU901',
 }

package/src/inspector.ts

@@ -58,6 +58,10 @@ export function getInitialInspectorState(rootDir: string): InspectorState {
       meta: {},
       files: new Set(),
     },
+    workflows: {
+      meta: {},
+      files: new Set(),
+    },
     rpc: {
       internalMeta: {},
       internalFiles: new Map(),

package/src/types.ts

@@ -2,7 +2,8 @@ import * as ts from 'typescript'
 import { ChannelsMeta } from '@pikku/core/channel'
 import { HTTPWiringsMeta } from '@pikku/core/http'
 import { ScheduledTasksMeta } from '@pikku/core/scheduler'
-import { queueWorkersMeta } from '@pikku/core/queue'
+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 { TypesMap } from './types-map.js'
@@ -205,7 +206,11 @@ export interface InspectorState {
     files: Set<string>
   }
   queueWorkers: {
-    meta: queueWorkersMeta
+    meta: QueueWorkersMeta
+    files: Set<string>
+  }
+  workflows: {
+    meta: WorkflowsMeta
     files: Set<string>
   }
   rpc: {

package/src/utils/extract-node-value.ts

@@ -0,0 +1,101 @@
+import * as ts from 'typescript'
+
+/**
+ * Extract string literal value from a TypeScript node.
+ * Handles string literals, template literals (including placeholders),
+ * and constant variable references.
+ */
+export function extractStringLiteral(
+  node: ts.Node,
+  checker: ts.TypeChecker
+): string {
+  if (ts.isStringLiteral(node)) {
+    return node.text
+  }
+
+  if (ts.isNoSubstitutionTemplateLiteral(node)) {
+    return node.text
+  }
+
+  if (ts.isTemplateExpression(node)) {
+    // reconstruct: `head + ${expr} + middle + ${expr} + tail`
+    let result = node.head.text
+    for (const span of node.templateSpans) {
+      const exprText = span.expression.getText()
+      result += '${' + exprText + '}' + span.literal.text
+    }
+    return result
+  }
+
+  // Try to evaluate constant identifiers
+  if (ts.isIdentifier(node)) {
+    const symbol = checker.getSymbolAtLocation(node)
+    if (
+      symbol?.valueDeclaration &&
+      ts.isVariableDeclaration(symbol.valueDeclaration)
+    ) {
+      const init = symbol.valueDeclaration.initializer
+      if (init) {
+        return extractStringLiteral(init, checker)
+      }
+    }
+  }
+
+  throw new Error('Unable to extract string literal from node')
+}
+
+/**
+ * Check if node is string-like (string literal or template expression)
+ */
+export function isStringLike(node: ts.Node, _checker: ts.TypeChecker): boolean {
+  if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
+    return true
+  }
+  // Check if it's a template string with substitutions
+  if (ts.isTemplateExpression(node)) {
+    return true
+  }
+  return false
+}
+
+/**
+ * Check if node is function-like (arrow, function expression, or function declaration)
+ */
+export function isFunctionLike(node: ts.Node): boolean {
+  return (
+    ts.isArrowFunction(node) ||
+    ts.isFunctionExpression(node) ||
+    ts.isFunctionDeclaration(node)
+  )
+}
+
+/**
+ * Extract number literal value from a node
+ */
+export function extractNumberLiteral(node: ts.Node): number | null {
+  if (ts.isNumericLiteral(node)) {
+    return Number(node.text)
+  }
+  return null
+}
+
+/**
+ * Extract a property value from an object literal expression
+ * Returns the extracted value or null if not found/cannot extract
+ */
+export function extractPropertyString(
+  objNode: ts.ObjectLiteralExpression,
+  propertyName: string,
+  checker: ts.TypeChecker
+): string | null {
+  for (const prop of objNode.properties) {
+    if (
+      ts.isPropertyAssignment(prop) &&
+      ts.isIdentifier(prop.name) &&
+      prop.name.text === propertyName
+    ) {
+      return extractStringLiteral(prop.initializer, checker)
+    }
+  }
+  return null
+}

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

@@ -112,6 +112,10 @@ export interface SerializableInspectorState {
     meta: InspectorState['queueWorkers']['meta']
     files: string[]
   }
+  workflows: {
+    meta: InspectorState['workflows']['meta']
+    files: string[]
+  }
   rpc: {
     internalMeta: InspectorState['rpc']['internalMeta']
     internalFiles: Array<[string, { path: string; exportedName: string }]>
@@ -243,6 +247,10 @@ export function serializeInspectorState(
       meta: state.queueWorkers.meta,
       files: Array.from(state.queueWorkers.files),
     },
+    workflows: {
+      meta: state.workflows.meta,
+      files: Array.from(state.workflows.files),
+    },
     rpc: {
       internalMeta: state.rpc.internalMeta,
       internalFiles: Array.from(state.rpc.internalFiles.entries()),
@@ -344,6 +352,10 @@ export function deserializeInspectorState(
       meta: data.queueWorkers.meta,
       files: new Set(data.queueWorkers.files),
     },
+    workflows: {
+      meta: data.workflows.meta,
+      files: new Set(data.workflows.files),
+    },
     rpc: {
       internalMeta: data.rpc.internalMeta,
       internalFiles: new Map(data.rpc.internalFiles),

package/src/utils/test-data/inspector-state.json

@@ -1260,6 +1260,10 @@
     },
     "files": ["src/queue-worker.wiring.ts"]
   },
+  "workflows": {
+    "meta": {},
+    "files": []
+  },
   "rpc": {
     "internalMeta": {
       "onConnect": "onConnect",

package/src/utils/type-utils.ts

@@ -4,6 +4,75 @@ export const extractTypeKeys = (type: ts.Type): string[] => {
   return type.getProperties().map((symbol) => symbol.getName())
 }
 
+/**
+ * Resolve an identifier or call expression to the actual function declaration
+ */
+export function resolveFunctionDeclaration(
+  node: ts.Node,
+  checker: ts.TypeChecker
+): ts.Node | null {
+  // If it's already a function-like node, return it
+  if (
+    ts.isFunctionDeclaration(node) ||
+    ts.isFunctionExpression(node) ||
+    ts.isArrowFunction(node)
+  ) {
+    return node
+  }
+
+  // If it's a call expression (e.g., pikkuWorkflowFunc(...)), get its first argument
+  if (ts.isCallExpression(node) && node.arguments.length > 0) {
+    const firstArg = node.arguments[0]
+    if (ts.isFunctionExpression(firstArg) || ts.isArrowFunction(firstArg)) {
+      return firstArg
+    }
+  }
+
+  // If it's an identifier, resolve to declaration
+  if (ts.isIdentifier(node)) {
+    const symbol = checker.getSymbolAtLocation(node)
+    if (!symbol) return null
+
+    // Try valueDeclaration first, then fallback to declarations[0]
+    const decl = symbol.valueDeclaration || symbol.declarations?.[0]
+    if (!decl) return null
+
+    // If it's an import specifier, resolve the aliased symbol
+    if (ts.isImportSpecifier(decl)) {
+      const aliasedSymbol = checker.getAliasedSymbol(symbol)
+      if (aliasedSymbol) {
+        const aliasedDecl =
+          aliasedSymbol.valueDeclaration || aliasedSymbol.declarations?.[0]
+        if (aliasedDecl) {
+          // For variable declarations, get the initializer
+          if (
+            ts.isVariableDeclaration(aliasedDecl) &&
+            aliasedDecl.initializer
+          ) {
+            return resolveFunctionDeclaration(aliasedDecl.initializer, checker)
+          }
+          // For function declarations, return directly
+          if (ts.isFunctionDeclaration(aliasedDecl)) {
+            return aliasedDecl
+          }
+        }
+      }
+    }
+
+    // If it's a variable declaration, get the initializer
+    if (ts.isVariableDeclaration(decl) && decl.initializer) {
+      return resolveFunctionDeclaration(decl.initializer, checker)
+    }
+
+    // If it's a function declaration
+    if (ts.isFunctionDeclaration(decl)) {
+      return decl
+    }
+  }
+
+  return null
+}
+
 export function getPropertyAssignmentInitializer(
   obj: ts.ObjectLiteralExpression,
   propName: string,

package/src/visit.ts

@@ -4,6 +4,7 @@ import { addFileExtendsCoreType } from './add/add-file-extends-core-type.js'
 import { addHTTPRoute } from './add/add-http-route.js'
 import { addSchedule } from './add/add-schedule.js'
 import { addQueueWorker } from './add/add-queue-worker.js'
+import { addWorkflow } from './add/add-workflow.js'
 import { addMCPResource } from './add/add-mcp-resource.js'
 import { addMCPTool } from './add/add-mcp-tool.js'
 import { addMCPPrompt } from './add/add-mcp-prompt.js'
@@ -74,6 +75,7 @@ export const visitSetup = (
   addRPCInvocations(node, state, logger)
   addMiddleware(logger, node, checker, state, options)
   addPermission(logger, node, checker, state, options)
+  addWorkflow(logger, node, checker, state, options)
 
   ts.forEachChild(node, (child) =>
     visitSetup(logger, checker, child, state, options)