@pikku/inspector 0.10.2 → 0.11.1

package/src/add/add-functions.ts

@@ -2,9 +2,12 @@ import * as ts from 'typescript'
 import { AddWiring } from '../types.js'
 import { TypesMap } from '../types-map.js'
 import { extractFunctionName } from '../utils/extract-function-name.js'
-import { getPropertyAssignmentInitializer } from '../utils/type-utils.js'
-import { FunctionServicesMeta, PikkuDocs } from '@pikku/core'
-import { getPropertyValue } from '../utils/get-property-value.js'
+import { extractFunctionNode } from '../utils/extract-function-node.js'
+import { FunctionServicesMeta } from '@pikku/core'
+import {
+  getPropertyValue,
+  getCommonWireMetaData,
+} from '../utils/get-property-value.js'
 import { resolveMiddleware } from '../utils/middleware.js'
 
 const isValidVariableName = (name: string) => {
@@ -304,54 +307,43 @@ export const addFunctions: AddWiring = (logger, node, checker, state) => {
     extractFunctionName(node, checker, state.rootDir)
 
   let tags: string[] | undefined
+  let summary: string | undefined
+  let description: string | undefined
+  let errors: string[] | undefined
   let expose: boolean | undefined
-  let docs: PikkuDocs | undefined
+  let internal: boolean | undefined
   let objectNode: ts.ObjectLiteralExpression | undefined
 
-  // determine the actual handler expression:
-  // either the `func` prop or the first argument directly
-  let handlerNode: ts.Expression = args[0]!
-  let isDirectFunction = true // Default to direct function format
-
-  if (ts.isObjectLiteralExpression(handlerNode)) {
-    isDirectFunction = false // This is object format with func property
-    objectNode = handlerNode
-    tags = (getPropertyValue(handlerNode, 'tags') as string[]) || undefined
-    expose = getPropertyValue(handlerNode, 'expose') as boolean | undefined
-    docs = getPropertyValue(handlerNode, 'docs') as PikkuDocs | undefined
-
-    const fnProp = getPropertyAssignmentInitializer(
-      handlerNode,
-      'func',
-      true,
-      checker
-    )
-    if (
-      !fnProp ||
-      (!ts.isArrowFunction(fnProp) && !ts.isFunctionExpression(fnProp))
-    ) {
-      logger.error(`• No valid 'func' property found for ${pikkuFuncName}.`)
-      // Create stub metadata to prevent "function not found" errors in wirings
-      state.functions.meta[pikkuFuncName] = {
-        pikkuFuncName,
-        name,
-        services: { optimized: false, services: [] },
-        inputSchemaName: null,
-        outputSchemaName: null,
-        inputs: [],
-        outputs: [],
-        middleware: undefined,
-      }
-      return
-    }
-    handlerNode = fnProp
+  // Extract the function node using shared utility
+  const firstArg = args[0]!
+  const {
+    funcNode: handlerNode,
+    resolvedFunc,
+    isDirectFunction,
+  } = extractFunctionNode(firstArg, checker)
+
+  // Extract config properties if using object form
+  if (ts.isObjectLiteralExpression(firstArg)) {
+    objectNode = firstArg
+    const metadata = getCommonWireMetaData(firstArg, 'Function', name, logger)
+    tags = metadata.tags
+    summary = metadata.summary
+    description = metadata.description
+    errors = metadata.errors
+    expose = getPropertyValue(firstArg, 'expose') as boolean | undefined
+    internal = getPropertyValue(firstArg, 'internal') as boolean | undefined
   }
 
-  if (
-    !ts.isArrowFunction(handlerNode) &&
-    !ts.isFunctionExpression(handlerNode)
-  ) {
-    logger.error(`• Handler for ${name} is not a function.`)
+  // Pick the handler: use resolvedFunc when it exists and is a function, otherwise fall back to handlerNode
+  const handler =
+    resolvedFunc &&
+    (ts.isArrowFunction(resolvedFunc) || ts.isFunctionExpression(resolvedFunc))
+      ? resolvedFunc
+      : handlerNode
+
+  // Validate that we got a valid function
+  if (!ts.isArrowFunction(handler) && !ts.isFunctionExpression(handler)) {
+    logger.error(`• No valid 'func' property found for ${pikkuFuncName}.`)
     // Create stub metadata to prevent "function not found" errors in wirings
     state.functions.meta[pikkuFuncName] = {
       pikkuFuncName,
@@ -371,7 +363,7 @@ export const addFunctions: AddWiring = (logger, node, checker, state) => {
     services: [],
   }
 
-  const firstParam = handlerNode.parameters[0]
+  const firstParam = handler.parameters[0]
   if (firstParam) {
     if (ts.isObjectBindingPattern(firstParam.name)) {
       for (const elem of firstParam.name.elements) {
@@ -390,6 +382,23 @@ export const addFunctions: AddWiring = (logger, node, checker, state) => {
     }
   }
 
+  // --- Extract used wires from third parameter ---
+  const usedWires: string[] = []
+  const thirdParam = handler.parameters[2]
+  if (thirdParam && ts.isObjectBindingPattern(thirdParam.name)) {
+    for (const elem of thirdParam.name.elements) {
+      const propertyName =
+        elem.propertyName && ts.isIdentifier(elem.propertyName)
+          ? elem.propertyName.text
+          : ts.isIdentifier(elem.name)
+            ? elem.name.text
+            : undefined
+      if (propertyName) {
+        usedWires.push(propertyName)
+      }
+    }
+  }
+
   // --- Generics → ts.Type[], unwrapped from Promise ---
   const genericTypes: ts.Type[] = (typeArguments ?? [])
     .map((tn) => checker.getTypeFromTypeNode(tn))
@@ -420,7 +429,7 @@ export const addFunctions: AddWiring = (logger, node, checker, state) => {
       genericTypes[1]
     ).names
   } else {
-    const sig = checker.getSignatureFromDeclaration(handlerNode)
+    const sig = checker.getSignatureFromDeclaration(handler)
     if (sig) {
       const rawRet = checker.getReturnTypeOfSignature(sig)
       const unwrapped = unwrapPromise(checker, rawRet)
@@ -440,6 +449,11 @@ export const addFunctions: AddWiring = (logger, node, checker, state) => {
     )
   }
 
+  // Store the input type for later use
+  if (inputTypes.length > 0) {
+    state.typesLookup.set(pikkuFuncName, inputTypes)
+  }
+
   // --- resolve middleware ---
   const middleware = objectNode
     ? resolveMiddleware(state, objectNode, tags, checker)
@@ -449,20 +463,19 @@ export const addFunctions: AddWiring = (logger, node, checker, state) => {
     pikkuFuncName,
     name,
     services,
+    usedWires: usedWires.length > 0 ? usedWires : undefined,
     inputSchemaName: inputNames[0] ?? null,
     outputSchemaName: outputNames[0] ?? null,
     inputs: inputNames.filter((n) => n !== 'void') ?? null,
     outputs: outputNames.filter((n) => n !== 'void') ?? null,
     expose: expose || undefined,
+    internal: internal || undefined,
     tags: tags || undefined,
-    docs: docs || undefined,
-    isDirectFunction,
+    summary,
+    description,
+    errors,
     middleware,
-  }
-
-  // Store the input type for later use
-  if (inputTypes.length > 0) {
-    state.typesLookup.set(pikkuFuncName, inputTypes)
+    isDirectFunction,
   }
 
   // Store function file location for wiring generation
@@ -473,6 +486,12 @@ export const addFunctions: AddWiring = (logger, node, checker, state) => {
     })
   }
 
+  // Workflow functions don't get registered as RPC functions,
+  // they are their own type handled by add-workdflow
+  if (expression.text.includes('Workflow')) {
+    return
+  }
+
   if (exportedName || explicitName) {
     if (!exportedName) {
       logger.error(
@@ -481,6 +500,11 @@ export const addFunctions: AddWiring = (logger, node, checker, state) => {
       return
     }
 
+    // Mark internal functions as invoked to force bundling
+    if (internal) {
+      state.rpc.invokedFunctions.add(pikkuFuncName)
+    }
+
     if (expose) {
       state.rpc.exposedMeta[name] = pikkuFuncName
       state.rpc.exposedFiles.set(name, {
@@ -496,8 +520,8 @@ export const addFunctions: AddWiring = (logger, node, checker, state) => {
 
     // But we only import the actual function if it's actually invoked to keep
     // bundle size down
-    if (state.rpc.invokedFunctions.has(pikkuFuncName) || expose) {
-      state.rpc.internalFiles.set(name, {
+    if (state.rpc.invokedFunctions.has(pikkuFuncName) || expose || internal) {
+      state.rpc.internalFiles.set(pikkuFuncName, {
         path: node.getSourceFile().fileName,
         exportedName,
       })

package/src/add/add-http-route.ts

@@ -1,11 +1,10 @@
 import * as ts from 'typescript'
 import {
   getPropertyValue,
-  getPropertyTags,
+  getCommonWireMetaData,
 } from '../utils/get-property-value.js'
 import { pathToRegexp } from 'path-to-regexp'
 import { HTTPMethod } from '@pikku/core/http'
-import { PikkuDocs } from '@pikku/core'
 import { extractFunctionName } from '../utils/extract-function-name.js'
 import { getPropertyAssignmentInitializer } from '../utils/type-utils.js'
 import { AddWiring } from '../types.js'
@@ -71,8 +70,12 @@ export const addHTTPRoute: AddWiring = (
 
   const method =
     (getPropertyValue(obj, 'method') as string)?.toLowerCase() || 'get'
-  const docs = (getPropertyValue(obj, 'docs') as PikkuDocs) || undefined
-  const tags = getPropertyTags(obj, 'HTTP route', route, logger)
+  const { tags, summary, description, errors } = getCommonWireMetaData(
+    obj,
+    'HTTP route',
+    route,
+    logger
+  )
   const query = (getPropertyValue(obj, 'query') as string[]) || []
 
   // --- find the referenced function name first for filtering ---
@@ -155,7 +158,9 @@ export const addHTTPRoute: AddWiring = (
     params: params.length > 0 ? params : undefined,
     query: query.length > 0 ? query : undefined,
     inputTypes,
-    docs,
+    summary,
+    description,
+    errors,
     tags,
     middleware,
     permissions,

package/src/add/add-mcp-prompt.ts

@@ -1,7 +1,7 @@
 import * as ts from 'typescript'
 import {
   getPropertyValue,
-  getPropertyTags,
+  getCommonWireMetaData,
 } from '../utils/get-property-value.js'
 import { extractWireNames } from '../utils/post-process.js'
 import { ensureFunctionMetadata } from '../utils/ensure-function-metadata.js'
@@ -40,10 +40,12 @@ export const addMCPPrompt: AddWiring = (
     const obj = firstArg
 
     const nameValue = getPropertyValue(obj, 'name') as string | null
-    const descriptionValue = getPropertyValue(obj, 'description') as
-      | string
-      | null
-    const tags = getPropertyTags(obj, 'MCP prompt', nameValue, logger)
+    const { tags, summary, description, errors } = getCommonWireMetaData(
+      obj,
+      'MCP prompt',
+      nameValue,
+      logger
+    )
 
     const funcInitializer = getPropertyAssignmentInitializer(
       obj,
@@ -76,7 +78,7 @@ export const addMCPPrompt: AddWiring = (
       return
     }
 
-    if (!descriptionValue) {
+    if (!description) {
       logger.critical(
         ErrorCode.MISSING_DESCRIPTION,
         `MCP prompt '${nameValue}' is missing a description.`
@@ -116,7 +118,9 @@ export const addMCPPrompt: AddWiring = (
     state.mcpEndpoints.promptsMeta[nameValue] = {
       pikkuFuncName,
       name: nameValue,
-      description: descriptionValue,
+      description,
+      summary,
+      errors,
       tags,
       inputSchema,
       outputSchema,

package/src/add/add-mcp-resource.ts

@@ -1,7 +1,7 @@
 import * as ts from 'typescript'
 import {
   getPropertyValue,
-  getPropertyTags,
+  getCommonWireMetaData,
 } from '../utils/get-property-value.js'
 import { extractWireNames } from '../utils/post-process.js'
 import { ensureFunctionMetadata } from '../utils/ensure-function-metadata.js'
@@ -41,11 +41,13 @@ export const addMCPResource: AddWiring = (
 
     const uriValue = getPropertyValue(obj, 'uri') as string | null
     const titleValue = getPropertyValue(obj, 'title') as string | null
-    const descriptionValue = getPropertyValue(obj, 'description') as
-      | string
-      | null
+    const { tags, summary, description, errors } = getCommonWireMetaData(
+      obj,
+      'MCP resource',
+      uriValue,
+      logger
+    )
     const streamingValue = getPropertyValue(obj, 'streaming') as boolean | null
-    const tags = getPropertyTags(obj, 'MCP resource', uriValue, logger)
 
     if (streamingValue === true) {
       logger.warn(
@@ -92,7 +94,7 @@ export const addMCPResource: AddWiring = (
       return
     }
 
-    if (!descriptionValue) {
+    if (!description) {
       logger.critical(
         ErrorCode.MISSING_DESCRIPTION,
         `MCP resource '${uriValue}' is missing a description.`
@@ -133,7 +135,9 @@ export const addMCPResource: AddWiring = (
       pikkuFuncName,
       uri: uriValue,
       title: titleValue,
-      description: descriptionValue,
+      description,
+      summary,
+      errors,
       ...(streamingValue !== null && { streaming: streamingValue }),
       tags,
       inputSchema,

package/src/add/add-mcp-tool.ts

@@ -1,7 +1,7 @@
 import * as ts from 'typescript'
 import {
   getPropertyValue,
-  getPropertyTags,
+  getCommonWireMetaData,
 } from '../utils/get-property-value.js'
 import { extractWireNames } from '../utils/post-process.js'
 import { ensureFunctionMetadata } from '../utils/ensure-function-metadata.js'
@@ -41,11 +41,13 @@ export const addMCPTool: AddWiring = (
 
     const nameValue = getPropertyValue(obj, 'name') as string | null
     const titleValue = getPropertyValue(obj, 'title') as string | null
-    const descriptionValue = getPropertyValue(obj, 'description') as
-      | string
-      | null
+    const { tags, summary, description, errors } = getCommonWireMetaData(
+      obj,
+      'MCP tool',
+      nameValue,
+      logger
+    )
     const streamingValue = getPropertyValue(obj, 'streaming') as boolean | null
-    const tags = getPropertyTags(obj, 'MCP tool', nameValue, logger)
 
     if (streamingValue === true) {
       logger.warn(
@@ -84,7 +86,7 @@ export const addMCPTool: AddWiring = (
       return
     }
 
-    if (!descriptionValue) {
+    if (!description) {
       logger.critical(
         ErrorCode.MISSING_DESCRIPTION,
         `MCP tool '${nameValue}' is missing a description.`
@@ -125,7 +127,9 @@ export const addMCPTool: AddWiring = (
       pikkuFuncName,
       name: nameValue,
       title: titleValue || undefined,
-      description: descriptionValue,
+      description,
+      summary,
+      errors,
       ...(streamingValue !== null && { streaming: streamingValue }),
       tags,
       inputSchema,

package/src/add/add-middleware.ts

@@ -125,7 +125,7 @@ export const addMiddleware: AddWiring = (logger, node, checker, state) => {
       }
     } else {
       // No pikkuMiddleware wrapper found - extract from factory's return value directly
-      // Factory pattern: (config) => (services, interaction, next) => { ... }
+      // Factory pattern: (config) => (services, wire, next) => { ... }
       if (
         ts.isArrowFunction(factoryNode) ||
         ts.isFunctionExpression(factoryNode)

package/src/add/add-permission.ts

@@ -125,7 +125,7 @@ export const addPermission: AddWiring = (logger, node, checker, state) => {
       }
     } else {
       // No pikkuPermission wrapper found - extract from factory's return value directly
-      // Factory pattern: (config) => (services, data, session) => { ... }
+      // Factory pattern: (config) => (services, data, wire) => { ... }
       if (
         ts.isArrowFunction(factoryNode) ||
         ts.isFunctionExpression(factoryNode)

package/src/add/add-queue-worker.ts

@@ -1,9 +1,8 @@
 import * as ts from 'typescript'
 import {
   getPropertyValue,
-  getPropertyTags,
+  getCommonWireMetaData,
 } from '../utils/get-property-value.js'
-import { PikkuDocs } from '@pikku/core'
 import { AddWiring } from '../types.js'
 import { extractFunctionName } from '../utils/extract-function-name.js'
 import { getPropertyAssignmentInitializer } from '../utils/type-utils.js'
@@ -11,13 +10,7 @@ import { resolveMiddleware } from '../utils/middleware.js'
 import { extractWireNames } from '../utils/post-process.js'
 import { ErrorCode } from '../error-codes.js'
 
-export const addQueueWorker: AddWiring = (
-  logger,
-  node,
-  checker,
-  state,
-  options
-) => {
+export const addQueueWorker: AddWiring = (logger, node, checker, state) => {
   if (!ts.isCallExpression(node)) {
     return
   }
@@ -39,8 +32,12 @@ export const addQueueWorker: AddWiring = (
     const obj = firstArg
 
     const queueName = getPropertyValue(obj, 'queueName') as string | null
-    const docs = (getPropertyValue(obj, 'docs') as PikkuDocs) || undefined
-    const tags = getPropertyTags(obj, 'Queue worker', queueName, logger)
+    const { tags, summary, description, errors } = getCommonWireMetaData(
+      obj,
+      'Queue worker',
+      queueName,
+      logger
+    )
 
     // --- find the referenced function ---
     const funcInitializer = getPropertyAssignmentInitializer(
@@ -84,7 +81,9 @@ export const addQueueWorker: AddWiring = (
     state.queueWorkers.meta[queueName] = {
       pikkuFuncName,
       queueName,
-      docs,
+      summary,
+      description,
+      errors,
       tags,
       middleware,
     }

package/src/add/add-schedule.ts

@@ -1,9 +1,8 @@
 import * as ts from 'typescript'
 import {
   getPropertyValue,
-  getPropertyTags,
+  getCommonWireMetaData,
 } from '../utils/get-property-value.js'
-import { PikkuDocs } from '@pikku/core'
 import { AddWiring } from '../types.js'
 import { extractFunctionName } from '../utils/extract-function-name.js'
 import { getPropertyAssignmentInitializer } from '../utils/type-utils.js'
@@ -40,8 +39,12 @@ export const addSchedule: AddWiring = (
 
     const nameValue = getPropertyValue(obj, 'name') as string | null
     const scheduleValue = getPropertyValue(obj, 'schedule') as string | null
-    const docs = (getPropertyValue(obj, 'docs') as PikkuDocs) || undefined
-    const tags = getPropertyTags(obj, 'Scheduler', nameValue, logger)
+    const { tags, summary, description, errors } = getCommonWireMetaData(
+      obj,
+      'Scheduler',
+      nameValue,
+      logger
+    )
 
     const funcInitializer = getPropertyAssignmentInitializer(
       obj,
@@ -81,7 +84,9 @@ export const addSchedule: AddWiring = (
       pikkuFuncName,
       name: nameValue,
       schedule: scheduleValue,
-      docs,
+      summary,
+      description,
+      errors,
       tags,
       middleware,
     }