@pikku/inspector 0.11.1 → 0.12.0

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
   }
@@ -131,7 +182,7 @@ export const addWorkflow: AddWiring = (logger, node, checker, state) => {
   }
 
   // Extract workflow name and metadata using same logic as add-functions
-  const { pikkuFuncName, name, exportedName } = extractFunctionName(
+  const { pikkuFuncId, name, exportedName } = extractFunctionName(
     node,
     checker,
     state.rootDir
@@ -163,6 +214,7 @@ export const addWorkflow: AddWiring = (logger, node, checker, state) => {
       workflowName,
       logger
     )
+    if (metadata.disabled) return
     tags = metadata.tags
     summary = metadata.summary
     description = metadata.description
@@ -191,48 +243,83 @@ export const addWorkflow: AddWiring = (logger, node, checker, state) => {
 
   // Track workflow file for wiring generation
   if (exportedName) {
-    state.workflows.files.set(pikkuFuncName, {
+    state.workflows.files.set(pikkuFuncId, {
       path: node.getSourceFile().fileName,
       exportedName,
     })
   }
 
   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,
+    pikkuFuncId,
+    name: 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,11 +30,16 @@ export enum ErrorCode {
   SCHEMA_NO_ROOT = 'PKU431',
   SCHEMA_GENERATION_ERROR = 'PKU456',
   SCHEMA_LOAD_ERROR = 'PKU488',
+  INLINE_SCHEMA = 'PKU489',
 
   // Function errors
   FUNCTION_METADATA_NOT_FOUND = 'PKU559',
   HANDLER_NOT_RESOLVED = 'PKU568',
 
+  // HTTP Route errors
+  ROUTE_PARAM_MISMATCH = 'PKU571',
+  ROUTE_QUERY_MISMATCH = 'PKU572',
+
   // Middleware/Permission errors
   MIDDLEWARE_HANDLER_INVALID = 'PKU685',
   MIDDLEWARE_TAG_INVALID = 'PKU715',
@@ -44,6 +50,25 @@ export enum ErrorCode {
   PERMISSION_EMPTY_ARRAY = 'PKU937',
   PERMISSION_PATTERN_INVALID = 'PKU975',
 
+  // Versioning errors
+  DUPLICATE_FUNCTION_VERSION = 'PKU850',
+
+  // Contract versioning errors
+  MANIFEST_MISSING = 'PKU860',
+  FUNCTION_VERSION_MODIFIED = 'PKU861',
+  CONTRACT_CHANGED_REQUIRES_BUMP = 'PKU862',
+  VERSION_REGRESSION_OR_CONFLICT = 'PKU863',
+  VERSION_GAP_NOT_ALLOWED = 'PKU864',
+  MANIFEST_INTEGRITY_ERROR = 'PKU865',
+
+  // Model configuration errors
+  MISSING_MODEL = 'PKU145',
+  INVALID_MODEL = 'PKU146',
+
+  // Optimization diagnostics
+  SERVICES_NOT_DESTRUCTURED = 'PKU410',
+  WIRES_NOT_DESTRUCTURED = 'PKU411',
+
   // Feature Flag
   WORKFLOW_MULTI_QUEUE_NOT_SUPPORTED = 'PKU901',
 }

package/src/index.ts

@@ -1,12 +1,7 @@
 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'
-export type { InspectorState } from './types.js'
-export type {
-  FilesAndMethods,
-  FilesAndMethodsErrors,
-} from './utils/get-files-and-methods.js'
+export type { FilesAndMethodsErrors } from './utils/get-files-and-methods.js'
 export { ErrorCode } from './error-codes.js'
 export {
   serializeInspectorState,
@@ -14,5 +9,29 @@ 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'
+export {
+  generateCustomTypes,
+  sanitizeTypeName,
+} from './utils/custom-types-generator.js'
+export {
+  createEmptyManifest,
+  serializeManifest,
+} from './utils/contract-hashes.js'
+export type {
+  ContractEntry,
+  VersionValidateError,
+  VersionManifest,
+  VersionManifestEntry,
+} from './utils/contract-hashes.js'
+export { serializeMCPJson } from './utils/serialize-mcp-json.js'
+export type { OpenAPISpecInfo } from './utils/serialize-openapi-json.js'
+export {
+  deserializeDslWorkflow,
+  deserializeGraphWorkflow,
+  deserializeAllDslWorkflows,
+} from './utils/workflow/dsl/index.js'
+export { getFilesAndMethods } from './utils/get-files-and-methods.js'
+export type {
+  SerializedWorkflowGraph,
+  SerializedWorkflowGraphs,
+} from './utils/workflow/graph/index.js'

package/src/inspector.ts

@@ -7,8 +7,31 @@ import { getFilesAndMethods } from './utils/get-files-and-methods.js'
 import { findCommonAncestor } from './utils/find-root-dir.js'
 import {
   aggregateRequiredServices,
-  extractServiceInterfaceMetadata,
+  validateSecretOverrides,
+  validateAgentModels,
+  validateAgentOverrides,
+  computeResolvedIOTypes,
+  computeMiddlewareGroupsMeta,
+  computePermissionsGroupsMeta,
+  computeRequiredSchemas,
+  computeDiagnostics,
 } from './utils/post-process.js'
+import { generateOpenAPISpec } from './utils/serialize-openapi-json.js'
+import { pikkuState } from '@pikku/core'
+import { resolveLatestVersions } from './utils/resolve-versions.js'
+import { finalizeWorkflows } from './utils/workflow/graph/finalize-workflows.js'
+import {
+  finalizeWorkflowHelperTypes,
+  finalizeWorkflowWires,
+} from './utils/workflow/graph/finalize-workflow-wires.js'
+import { generateAllSchemas } from './utils/schema-generator.js'
+import {
+  computeContractHashes,
+  extractContractsFromMeta,
+  updateManifest,
+  createEmptyManifest,
+  validateContracts,
+} from './utils/contract-hashes.js'
 
 /**
  * Creates an initial/empty inspector state with all required properties initialized
@@ -29,6 +52,8 @@ export function getInitialInspectorState(rootDir: string): InspectorState {
     filesAndMethods: {},
     filesAndMethodsErrors: new Map(),
     typesLookup: new Map(),
+    schemaLookup: new Map(),
+    schemas: {},
     functions: {
       typesMap: new TypesMap(),
       meta: {},
@@ -53,6 +78,11 @@ export function getInitialInspectorState(rootDir: string): InspectorState {
       files: new Set(),
       meta: {},
     },
+    triggers: {
+      meta: {},
+      sourceMeta: {},
+      files: new Set(),
+    },
     scheduledTasks: {
       meta: {},
       files: new Set(),
@@ -64,6 +94,9 @@ export function getInitialInspectorState(rootDir: string): InspectorState {
     workflows: {
       meta: {},
       files: new Map(),
+      graphMeta: {},
+      graphFiles: new Map(),
+      invokedWorkflows: new Set(),
     },
     rpc: {
       internalMeta: {},
@@ -71,6 +104,7 @@ export function getInitialInspectorState(rootDir: string): InspectorState {
       exposedMeta: {},
       exposedFiles: new Map(),
       invokedFunctions: new Set(),
+      usedExternalPackages: new Set(),
     },
     mcpEndpoints: {
       resourcesMeta: {},
@@ -78,6 +112,10 @@ export function getInitialInspectorState(rootDir: string): InspectorState {
       promptsMeta: {},
       files: new Set(),
     },
+    agents: {
+      agentsMeta: {},
+      files: new Map(),
+    },
     cli: {
       meta: {
         programs: {},
@@ -85,12 +123,39 @@ export function getInitialInspectorState(rootDir: string): InspectorState {
       },
       files: new Set(),
     },
-    middleware: {
+    nodes: {
       meta: {},
+      files: new Set(),
+    },
+    secrets: {
+      definitions: [],
+      files: new Set(),
+    },
+    variables: {
+      definitions: [],
+      files: new Set(),
+    },
+    manifest: {
+      initial: null,
+      current: null,
+      errors: [],
+    },
+    middleware: {
+      definitions: {},
+      instances: {},
+      tagMiddleware: new Map(),
+    },
+    channelMiddleware: {
+      definitions: {},
+      instances: {},
       tagMiddleware: new Map(),
     },
+    aiMiddleware: {
+      definitions: {},
+    },
     permissions: {
-      meta: {},
+      definitions: {},
+      instances: {},
       tagPermissions: new Map(),
     },
     serviceAggregation: {
@@ -101,22 +166,41 @@ export function getInitialInspectorState(rootDir: string): InspectorState {
       allSingletonServices: [],
       allWireServices: [],
     },
-    serviceMetadata: [],
+    resolvedIOTypes: {},
+    middlewareGroupsMeta: {
+      definitions: {},
+      instances: {},
+      httpGroups: {},
+      tagGroups: {},
+      channelMiddleware: {
+        definitions: {},
+        instances: {},
+        tagGroups: {},
+      },
+    },
+    permissionsGroupsMeta: {
+      definitions: {},
+      httpGroups: {},
+      tagGroups: {},
+    },
+    requiredSchemas: new Set(),
+    openAPISpec: null,
+    diagnostics: [],
   }
 }
 
-export const inspect = (
+export const inspect = async (
   logger: InspectorLogger,
   routeFiles: string[],
   options: InspectorOptions = {}
-): InspectorState => {
+): Promise<InspectorState> => {
   const startProgram = performance.now()
   const program = ts.createProgram(routeFiles, {
     target: ts.ScriptTarget.ESNext,
-    module: ts.ModuleKind.CommonJS,
+    module: ts.ModuleKind.Node16,
     skipLibCheck: true,
     skipDefaultLibCheck: true,
-    moduleResolution: ts.ModuleResolutionKind.Node10,
+    moduleResolution: ts.ModuleResolutionKind.Node16,
     types: [],
     allowJs: false,
     checkJs: false,
@@ -131,15 +215,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
@@ -164,6 +252,32 @@ export const inspect = (
     logger.debug(
       `Visit routes phase completed in ${(performance.now() - startRoutes).toFixed(2)}ms`
     )
+
+    resolveLatestVersions(state, logger)
+
+    if (options.schemaConfig) {
+      state.schemas = await generateAllSchemas(
+        logger,
+        options.schemaConfig,
+        state
+      )
+      computeContractHashes(
+        state.schemas,
+        state.functions.typesMap,
+        state.functions.meta
+      )
+      computeRequiredSchemas(state, options)
+    }
+
+    state.manifest.initial = options.manifest ?? null
+    const contracts = extractContractsFromMeta(state.functions.meta)
+    const baseManifest = state.manifest.initial ?? createEmptyManifest()
+    state.manifest.current = updateManifest(baseManifest, contracts)
+    state.manifest.errors = validateContracts(baseManifest, contracts).errors
+
+    finalizeWorkflows(state)
+    finalizeWorkflowHelperTypes(state)
+    finalizeWorkflowWires(state)
   }
 
   // Populate filesAndMethods
@@ -182,11 +296,25 @@ export const inspect = (
       `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`
-    )
+    computeResolvedIOTypes(state)
+    computeMiddlewareGroupsMeta(state)
+    computePermissionsGroupsMeta(state)
+    computeDiagnostics(state)
+
+    if (options.openAPI) {
+      state.openAPISpec = await generateOpenAPISpec(
+        logger,
+        state.functions.meta,
+        state.http.meta,
+        state.schemas,
+        options.openAPI.additionalInfo,
+        pikkuState(null, 'misc', 'errors')
+      )
+    }
+
+    validateSecretOverrides(logger, state, options.externalPackages)
+    validateAgentModels(logger, state, options.modelConfig)
+    validateAgentOverrides(logger, state, options.modelConfig)
   }
 
   return state

package/src/schema-generator.ts

@@ -0,0 +1 @@
+export { generateAllSchemas } from './utils/schema-generator.js'

package/src/types-map.ts

@@ -28,7 +28,18 @@ export class TypesMap {
     uniqueName: string
     path: string | null
   } {
-    if (['string', 'number', 'boolean', 'null'].includes(name)) {
+    if (
+      [
+        'string',
+        'number',
+        'boolean',
+        'null',
+        'undefined',
+        'void',
+        'unknown',
+        'never',
+      ].includes(name)
+    ) {
       return {
         originalName: name,
         uniqueName: name,