@pikku/inspector 0.10.1 → 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/index.ts

@@ -1,4 +1,4 @@
-export { inspect } from './inspector.js'
+export { inspect, getInitialInspectorState } from './inspector.js'
 export { getFilesAndMethods } from './utils/get-files-and-methods.js'
 export type { TypesMap } from './types-map.js'
 export type * from './types.js'

package/src/inspector.ts

@@ -1,4 +1,5 @@
 import * as ts from 'typescript'
+import { performance } from 'perf_hooks'
 import { visitSetup, visitRoutes } from './visit.js'
 import { TypesMap } from './types-map.js'
 import { InspectorState, InspectorLogger, InspectorOptions } from './types.js'
@@ -6,22 +7,13 @@ import { getFilesAndMethods } from './utils/get-files-and-methods.js'
 import { findCommonAncestor } from './utils/find-root-dir.js'
 import { aggregateRequiredServices } from './utils/post-process.js'
 
-export const inspect = (
-  logger: InspectorLogger,
-  routeFiles: string[],
-  options: InspectorOptions = {}
-): InspectorState => {
-  const program = ts.createProgram(routeFiles, {
-    target: ts.ScriptTarget.ESNext,
-    module: ts.ModuleKind.CommonJS,
-  })
-  const checker = program.getTypeChecker()
-  const sourceFiles = program.getSourceFiles()
-
-  // Infer root directory from source files
-  const rootDir = findCommonAncestor(routeFiles)
-
-  const state: InspectorState = {
+/**
+ * Creates an initial/empty inspector state with all required properties initialized
+ * @param rootDir - The root directory for the project
+ * @returns A fresh InspectorState with empty collections
+ */
+export function getInitialInspectorState(rootDir: string): InspectorState {
+  return {
     rootDir,
     singletonServicesTypeImportMap: new Map(),
     sessionServicesTypeImportMap: new Map(),
@@ -66,6 +58,10 @@ export const inspect = (
       meta: {},
       files: new Set(),
     },
+    workflows: {
+      meta: {},
+      files: new Set(),
+    },
     rpc: {
       internalMeta: {},
       internalFiles: new Map(),
@@ -99,30 +95,89 @@ export const inspect = (
       usedFunctions: new Set(),
       usedMiddleware: new Set(),
       usedPermissions: new Set(),
+      allSingletonServices: [],
+      allSessionServices: [],
     },
   }
+}
+
+export const inspect = (
+  logger: InspectorLogger,
+  routeFiles: string[],
+  options: InspectorOptions = {}
+): InspectorState => {
+  const startProgram = performance.now()
+  const program = ts.createProgram(routeFiles, {
+    target: ts.ScriptTarget.ESNext,
+    module: ts.ModuleKind.CommonJS,
+    skipLibCheck: true,
+    skipDefaultLibCheck: true,
+    moduleResolution: ts.ModuleResolutionKind.Node10,
+    types: [],
+    allowJs: false,
+    checkJs: false,
+  })
+  logger.debug(
+    `Created program in ${(performance.now() - startProgram).toFixed(2)}ms`
+  )
+
+  const startChecker = performance.now()
+  const checker = program.getTypeChecker()
+  logger.debug(
+    `Got type checker in ${(performance.now() - startChecker).toFixed(2)}ms`
+  )
+
+  const startSourceFiles = performance.now()
+  const sourceFiles = program.getSourceFiles()
+  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
+  const startSetup = performance.now()
   for (const sourceFile of sourceFiles) {
     ts.forEachChild(sourceFile, (child) =>
       visitSetup(logger, checker, child, state, options)
     )
   }
+  logger.debug(
+    `Visit setup phase completed in ${(performance.now() - startSetup).toFixed(2)}ms`
+  )
 
-  // Second sweep: add all transports
-  for (const sourceFile of sourceFiles) {
-    ts.forEachChild(sourceFile, (child) =>
-      visitRoutes(logger, checker, child, state, options)
+  if (!options.setupOnly) {
+    // Second sweep: add all transports
+    const startRoutes = performance.now()
+    for (const sourceFile of sourceFiles) {
+      ts.forEachChild(sourceFile, (child) =>
+        visitRoutes(logger, checker, child, state, options)
+      )
+    }
+    logger.debug(
+      `Visit routes phase completed in ${(performance.now() - startRoutes).toFixed(2)}ms`
     )
   }
 
   // Populate filesAndMethods
+  const startFilesAndMethods = performance.now()
   const { result, errors } = getFilesAndMethods(state, options.types)
   state.filesAndMethods = result
   state.filesAndMethodsErrors = errors
+  logger.debug(
+    `Get files and methods completed in ${(performance.now() - startFilesAndMethods).toFixed(2)}ms`
+  )
 
-  // Post-processing: Aggregate required services from wired functions/middleware/permissions
-  aggregateRequiredServices(state)
+  if (!options.setupOnly) {
+    const startAggregate = performance.now()
+    aggregateRequiredServices(state)
+    logger.debug(
+      `Aggregate required services completed in ${(performance.now() - startAggregate).toFixed(2)}ms`
+    )
+  }
 
   return state
 }

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'
@@ -114,6 +115,7 @@ export type InspectorFilters = {
 }
 
 export type InspectorOptions = Partial<{
+  setupOnly: boolean
   types: Partial<{
     configFileType: string
     userSessionType: string
@@ -204,7 +206,11 @@ export interface InspectorState {
     files: Set<string>
   }
   queueWorkers: {
-    meta: queueWorkersMeta
+    meta: QueueWorkersMeta
+    files: Set<string>
+  }
+  workflows: {
+    meta: WorkflowsMeta
     files: Set<string>
   }
   rpc: {
@@ -231,5 +237,7 @@ export interface InspectorState {
     usedFunctions: Set<string> // Function names actually wired/exposed
     usedMiddleware: Set<string> // Middleware names used by wired functions
     usedPermissions: Set<string> // Permission names used by wired functions
+    allSingletonServices: string[] // All services available in SingletonServices type
+    allSessionServices: string[] // All services available in Services type (excluding SingletonServices)
   }
 }

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/post-process.ts

@@ -4,6 +4,7 @@ import {
   MiddlewareMetadata,
   PermissionMetadata,
 } from '@pikku/core'
+import { extractTypeKeys } from './type-utils.js'
 
 /**
  * Helper to extract wire-level middleware/permission names from metadata.
@@ -28,7 +29,7 @@ export function extractWireNames(
  */
 function expandAndAddGroupServices(
   list: MiddlewareMetadata[] | PermissionMetadata[] | undefined,
-  state: InspectorState,
+  state: InspectorState | Omit<InspectorState, 'typesLookup'>,
   addServices: (services: FunctionServicesMeta | undefined) => void,
   isMiddleware: boolean
 ): void {
@@ -57,6 +58,38 @@ function expandAndAddGroupServices(
   }
 }
 
+/**
+ * Extracts all service names from SingletonServices and Services types.
+ * This provides the complete list of available services for code generation.
+ * Only runs if typesLookup is available (omitted in deserialized states).
+ */
+function extractAllServices(
+  state: InspectorState | Omit<InspectorState, 'typesLookup'>
+): void {
+  // Skip if typesLookup is not available (e.g., deserialized state)
+  if (!('typesLookup' in state)) {
+    return
+  }
+
+  // Extract all singleton services from the SingletonServices type
+  const singletonServicesTypes = state.typesLookup.get('SingletonServices')
+  if (singletonServicesTypes && singletonServicesTypes.length > 0) {
+    const singletonServiceNames = extractTypeKeys(singletonServicesTypes[0])
+    state.serviceAggregation.allSingletonServices = singletonServiceNames.sort()
+  }
+
+  // Extract all services from the Services type
+  const servicesTypes = state.typesLookup.get('Services')
+  if (servicesTypes && servicesTypes.length > 0) {
+    const allServiceNames = extractTypeKeys(servicesTypes[0])
+    // Session services are those in Services but not in SingletonServices
+    const singletonSet = new Set(state.serviceAggregation.allSingletonServices)
+    state.serviceAggregation.allSessionServices = allServiceNames
+      .filter((name) => !singletonSet.has(name))
+      .sort()
+  }
+}
+
 /**
  * Aggregates all required services from wired functions, middleware, and permissions.
  * Must be called after AST traversal completes.
@@ -64,7 +97,12 @@ function expandAndAddGroupServices(
  * Note: usedFunctions, usedMiddleware, and usedPermissions are tracked directly
  * in the add-* methods during AST traversal for efficiency.
  */
-export function aggregateRequiredServices(state: InspectorState): void {
+export function aggregateRequiredServices(
+  state: InspectorState | Omit<InspectorState, 'typesLookup'>
+): void {
+  // First, extract all available services from types
+  extractAllServices(state)
+
   const { requiredServices, usedFunctions, usedMiddleware, usedPermissions } =
     state.serviceAggregation
 

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 }]>
@@ -162,6 +166,8 @@ export interface SerializableInspectorState {
     usedFunctions: string[]
     usedMiddleware: string[]
     usedPermissions: string[]
+    allSingletonServices: string[]
+    allSessionServices: string[]
   }
 }
 
@@ -241,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()),
@@ -271,6 +281,8 @@ export function serializeInspectorState(
       usedFunctions: Array.from(state.serviceAggregation.usedFunctions),
       usedMiddleware: Array.from(state.serviceAggregation.usedMiddleware),
       usedPermissions: Array.from(state.serviceAggregation.usedPermissions),
+      allSingletonServices: state.serviceAggregation.allSingletonServices,
+      allSessionServices: state.serviceAggregation.allSessionServices,
     },
   }
 }
@@ -340,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),
@@ -370,6 +386,8 @@ export function deserializeInspectorState(
       usedFunctions: new Set(data.serviceAggregation.usedFunctions),
       usedMiddleware: new Set(data.serviceAggregation.usedMiddleware),
       usedPermissions: new Set(data.serviceAggregation.usedPermissions),
+      allSingletonServices: data.serviceAggregation.allSingletonServices,
+      allSessionServices: data.serviceAggregation.allSessionServices,
     },
   }
 }

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",