@pikku/inspector 0.10.2 → 0.11.1

package/src/add/add-workflow.ts

@@ -0,0 +1,241 @@
+import * as ts from 'typescript'
+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 {
+  extractStringLiteral,
+  isStringLike,
+  isFunctionLike,
+  extractDescription,
+  extractDuration,
+} from '../utils/extract-node-value.js'
+import { extractSimpleWorkflow } from '../workflow/extract-simple-workflow.js'
+import { getCommonWireMetaData } from '../utils/get-property-value.js'
+
+/**
+ * Scan for workflow.do(), workflow.sleep(), and workflow.cancel() 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' || name.text === 'cancel') {
+      // 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,
+            })
+            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>',
+          })
+        } else if (name.text === 'cancel') {
+          // workflow.cancel(reason?)
+          steps.push({
+            type: 'cancel',
+          })
+        }
+      }
+    }
+  }
+
+  // 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)
+  })
+}
+
+/**
+ * Inspector for pikkuWorkflow() and pikkuSimpleWorkflow() calls
+ * Detects workflow registration and extracts metadata
+ */
+export const addWorkflow: AddWiring = (logger, node, checker, state) => {
+  if (!ts.isCallExpression(node)) {
+    return
+  }
+
+  const args = node.arguments
+  const firstArg = args[0]
+  const expression = node.expression
+
+  if (!ts.isIdentifier(expression)) {
+    return
+  }
+
+  let wrapperType: 'simple' | 'regular' | null = null
+  if (expression.text === 'pikkuWorkflowFunc') {
+    wrapperType = 'regular'
+  } else if (expression.text === 'pikkuSimpleWorkflowFunc') {
+    wrapperType = 'simple'
+  } else {
+    return
+  }
+
+  if (!firstArg) {
+    return
+  }
+
+  // Extract workflow name and metadata using same logic as add-functions
+  const { pikkuFuncName, name, exportedName } = extractFunctionName(
+    node,
+    checker,
+    state.rootDir
+  )
+
+  const workflowName = exportedName || name
+
+  if (!workflowName) {
+    logger.critical(
+      ErrorCode.MISSING_NAME,
+      `Could not determine workflow name from export.`
+    )
+    return
+  }
+
+  // Extract the function node (either direct function or from config.func)
+  const { funcNode, resolvedFunc } = extractFunctionNode(firstArg, checker)
+
+  // Extract metadata if using object form
+  let tags: string[] | undefined
+  let summary: string | undefined
+  let description: string | undefined
+  let errors: string[] | undefined
+
+  if (ts.isObjectLiteralExpression(firstArg)) {
+    const metadata = getCommonWireMetaData(
+      firstArg,
+      'Workflow',
+      workflowName,
+      logger
+    )
+    tags = metadata.tags
+    summary = metadata.summary
+    description = metadata.description
+    errors = metadata.errors
+  }
+
+  // Validate that we got a valid function
+  if (
+    ts.isObjectLiteralExpression(firstArg) &&
+    (!funcNode || funcNode === firstArg)
+  ) {
+    logger.critical(
+      ErrorCode.MISSING_FUNC,
+      `No valid 'func' property for workflow '${workflowName}'.`
+    )
+    return
+  }
+
+  if (!resolvedFunc) {
+    logger.critical(
+      ErrorCode.MISSING_FUNC,
+      `Could not resolve workflow function for '${workflowName}'.`
+    )
+    return
+  }
+
+  // Track workflow file for wiring generation
+  if (exportedName) {
+    state.workflows.files.set(pikkuFuncName, {
+      path: node.getSourceFile().fileName,
+      exportedName,
+    })
+  }
+
+  let steps: WorkflowStepMeta[] = []
+  let simple: boolean | undefined = undefined
+
+  // Try simple workflow extraction first
+  // Pass the whole CallExpression node so findWorkflowFunction can find the arrow function
+  const result = extractSimpleWorkflow(node, checker)
+
+  if (result.status === 'ok' && result.steps) {
+    // Simple extraction succeeded
+    steps = result.steps
+    simple = true
+  } else {
+    // Simple extraction failed
+    if (wrapperType === 'simple') {
+      // For pikkuSimpleWorkflowFunc, this is a critical error
+      logger.critical(
+        ErrorCode.INVALID_SIMPLE_WORKFLOW,
+        `Workflow '${workflowName}' uses pikkuSimpleWorkflowFunc but does not conform to simple workflow DSL:\n${result.reason || 'Unknown error'}`
+      )
+      return
+    } else {
+      // For pikkuWorkflowFunc, 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.`
+      )
+      simple = false
+    }
+  }
+
+  getWorkflowInvocations(resolvedFunc, checker, state, workflowName, steps)
+
+  state.workflows.meta[workflowName] = {
+    pikkuFuncName,
+    workflowName,
+    steps,
+    simple,
+    summary,
+    description,
+    errors,
+    tags,
+  }
+}

package/src/error-codes.ts

@@ -19,6 +19,9 @@ 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',
+  INVALID_SIMPLE_WORKFLOW = 'PKU641',
 
   // Configuration errors
   CONFIG_TYPE_NOT_FOUND = 'PKU426',
@@ -40,4 +43,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

@@ -14,3 +14,5 @@ export {
 } from './utils/serialize-inspector-state.js'
 export type { SerializableInspectorState } from './utils/serialize-inspector-state.js'
 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'

package/src/inspector.ts

@@ -5,7 +5,10 @@ import { TypesMap } from './types-map.js'
 import { InspectorState, InspectorLogger, InspectorOptions } from './types.js'
 import { getFilesAndMethods } from './utils/get-files-and-methods.js'
 import { findCommonAncestor } from './utils/find-root-dir.js'
-import { aggregateRequiredServices } from './utils/post-process.js'
+import {
+  aggregateRequiredServices,
+  extractServiceInterfaceMetadata,
+} from './utils/post-process.js'
 
 /**
  * Creates an initial/empty inspector state with all required properties initialized
@@ -16,12 +19,12 @@ export function getInitialInspectorState(rootDir: string): InspectorState {
   return {
     rootDir,
     singletonServicesTypeImportMap: new Map(),
-    sessionServicesTypeImportMap: new Map(),
+    wireServicesTypeImportMap: new Map(),
     userSessionTypeImportMap: new Map(),
     configTypeImportMap: new Map(),
     singletonServicesFactories: new Map(),
-    sessionServicesFactories: new Map(),
-    sessionServicesMeta: new Map(),
+    wireServicesFactories: new Map(),
+    wireServicesMeta: new Map(),
     configFactories: new Map(),
     filesAndMethods: {},
     filesAndMethodsErrors: new Map(),
@@ -58,6 +61,10 @@ export function getInitialInspectorState(rootDir: string): InspectorState {
       meta: {},
       files: new Set(),
     },
+    workflows: {
+      meta: {},
+      files: new Map(),
+    },
     rpc: {
       internalMeta: {},
       internalFiles: new Map(),
@@ -92,8 +99,9 @@ export function getInitialInspectorState(rootDir: string): InspectorState {
       usedMiddleware: new Set(),
       usedPermissions: new Set(),
       allSingletonServices: [],
-      allSessionServices: [],
+      allWireServices: [],
     },
+    serviceMetadata: [],
   }
 }
 
@@ -173,6 +181,12 @@ export const inspect = (
     logger.debug(
       `Aggregate required services completed in ${(performance.now() - startAggregate).toFixed(2)}ms`
     )
+
+    const startServiceMeta = performance.now()
+    extractServiceInterfaceMetadata(state, checker)
+    logger.debug(
+      `Extract service metadata completed in ${(performance.now() - startServiceMeta).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'
@@ -119,7 +120,7 @@ export type InspectorOptions = Partial<{
     configFileType: string
     userSessionType: string
     singletonServicesFactoryType: string
-    sessionServicesFactoryType: string
+    wireServicesFactoryType: string
   }>
 }>
 
@@ -146,7 +147,7 @@ export interface InspectorFilesAndMethods {
     type: string
     typePath: string
   }
-  sessionServicesType?: {
+  wireServicesType?: {
     file: string
     variable: string
     type: string
@@ -176,7 +177,7 @@ export interface InspectorFilesAndMethods {
     type: string
     typePath: string
   }
-  sessionServicesFactory?: {
+  wireServicesFactory?: {
     file: string
     variable: string
     type: string
@@ -187,12 +188,12 @@ export interface InspectorFilesAndMethods {
 export interface InspectorState {
   rootDir: string // Root directory inferred from source files
   singletonServicesTypeImportMap: PathToNameAndType
-  sessionServicesTypeImportMap: PathToNameAndType
+  wireServicesTypeImportMap: PathToNameAndType
   userSessionTypeImportMap: PathToNameAndType
   configTypeImportMap: PathToNameAndType
   singletonServicesFactories: PathToNameAndType
-  sessionServicesFactories: PathToNameAndType
-  sessionServicesMeta: Map<string, string[]> // variable name -> singleton services consumed
+  wireServicesFactories: PathToNameAndType
+  wireServicesMeta: Map<string, string[]> // variable name -> singleton services consumed
   configFactories: PathToNameAndType
   filesAndMethods: InspectorFilesAndMethods
   filesAndMethodsErrors: Map<string, PathToNameAndType>
@@ -205,9 +206,13 @@ export interface InspectorState {
     files: Set<string>
   }
   queueWorkers: {
-    meta: queueWorkersMeta
+    meta: QueueWorkersMeta
     files: Set<string>
   }
+  workflows: {
+    meta: WorkflowsMeta
+    files: Map<string, { path: string; exportedName: string }>
+  }
   rpc: {
     internalMeta: Record<string, string>
     internalFiles: Map<string, { path: string; exportedName: string }>
@@ -233,6 +238,16 @@ export interface InspectorState {
     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)
+    allWireServices: string[] // All services available in Services type (excluding SingletonServices)
   }
+  serviceMetadata: Array<{
+    name: string
+    summary: string
+    description: string
+    package: string
+    path: string
+    version: string
+    interface: string
+    expandedProperties: Record<string, string>
+  }>
 }

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

@@ -0,0 +1,58 @@
+import * as ts from 'typescript'
+import {
+  getPropertyAssignmentInitializer,
+  resolveFunctionDeclaration,
+} from './type-utils.js'
+
+/**
+ * Extracts the actual function node from a pikkuFunc/pikkuWorkflowFunc call
+ * Handles both direct function form and config object form { func: ... }
+ */
+export function extractFunctionNode(
+  firstArg: ts.Expression,
+  checker: ts.TypeChecker
+): {
+  funcNode: ts.Node
+  resolvedFunc: ts.Node | null
+  isDirectFunction: boolean
+} {
+  let funcNode: ts.Node = firstArg
+  let isDirectFunction = true
+
+  // Check if first argument is a config object with 'func' property
+  if (ts.isObjectLiteralExpression(firstArg)) {
+    isDirectFunction = false
+    const funcInitializer = getPropertyAssignmentInitializer(
+      firstArg,
+      'func',
+      true,
+      checker
+    )
+
+    if (funcInitializer) {
+      funcNode = funcInitializer
+    } else {
+      // Return the original node if no func property found
+      // Caller should handle validation
+      funcNode = firstArg
+    }
+  }
+
+  // Resolve identifier to get the actual function node
+  if (ts.isIdentifier(funcNode)) {
+    const symbol = checker.getSymbolAtLocation(funcNode)
+    const decl = symbol?.valueDeclaration || symbol?.declarations?.[0]
+    if (decl && ts.isVariableDeclaration(decl) && decl.initializer) {
+      funcNode = decl.initializer
+    }
+  }
+
+  // Resolve function declaration for deeper analysis
+  const resolvedFunc = resolveFunctionDeclaration(funcNode, checker)
+
+  return {
+    funcNode,
+    resolvedFunc,
+    isDirectFunction,
+  }
+}

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

@@ -0,0 +1,132 @@
+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
+}
+
+/**
+ * Extract description from options object
+ */
+export 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)
+ */
+export function extractDuration(
+  node: ts.Node,
+  checker: ts.TypeChecker
+): string | number | null {
+  const numValue = extractNumberLiteral(node)
+  if (numValue !== null) {
+    return numValue
+  }
+  try {
+    return extractStringLiteral(node, checker)
+  } catch {
+    return null
+  }
+}