@pikku/inspector 0.11.1 → 0.12.0

package/src/add/add-functions.ts

@@ -1,14 +1,23 @@
 import * as ts from 'typescript'
-import { AddWiring } from '../types.js'
+import { AddWiring, SchemaRef } from '../types.js'
+import { detectSchemaVendorOrError } from '../utils/detect-schema-vendor.js'
 import { TypesMap } from '../types-map.js'
-import { extractFunctionName } from '../utils/extract-function-name.js'
+import {
+  extractFunctionName,
+  funcIdToTypeName,
+} from '../utils/extract-function-name.js'
 import { extractFunctionNode } from '../utils/extract-function-node.js'
-import { FunctionServicesMeta } from '@pikku/core'
+import { extractUsedWires } from '../utils/extract-services.js'
+import { FunctionServicesMeta, formatVersionedId } from '@pikku/core'
 import {
   getPropertyValue,
   getCommonWireMetaData,
 } from '../utils/get-property-value.js'
 import { resolveMiddleware } from '../utils/middleware.js'
+import { resolvePermissions } from '../utils/permissions.js'
+import { extractWireNames } from '../utils/post-process.js'
+import { ErrorCode } from '../error-codes.js'
+import type { NodeType } from '@pikku/core/node'
 
 const isValidVariableName = (name: string) => {
   const regex = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/
@@ -20,7 +29,8 @@ const nullifyTypes = (type: string | null) => {
     type === 'void' ||
     type === 'undefined' ||
     type === 'unknown' ||
-    type === 'any'
+    type === 'any' ||
+    type === 'null'
   ) {
     return null
   }
@@ -152,14 +162,18 @@ const resolveUnionTypes = (
   // Check if it's a union type AND not part of an intersection
   if (type.isUnion() && !(type.flags & ts.TypeFlags.Intersection)) {
     for (const t of type.types) {
-      const name = nullifyTypes(checker.typeToString(t))
+      const name = nullifyTypes(
+        checker.typeToString(t, undefined, ts.TypeFormatFlags.NoTruncation)
+      )
       if (name) {
         types.push(t)
         names.push(name)
       }
     }
   } else {
-    const name = nullifyTypes(checker.typeToString(type))
+    const name = nullifyTypes(
+      checker.typeToString(type, undefined, ts.TypeFormatFlags.NoTruncation)
+    )
     if (name) {
       types.push(type)
       names.push(name)
@@ -180,8 +194,8 @@ const getNamesAndTypes = (
     return { names: [], types: [] }
   }
 
-  // 1) Handle an explicit void (or undefined) type up front
-  if (type.flags & ts.TypeFlags.VoidLike) {
+  // 1) Handle an explicit void (or undefined or null) type up front
+  if (type.flags & (ts.TypeFlags.VoidLike | ts.TypeFlags.Null)) {
     return {
       names: [],
       types: [],
@@ -199,8 +213,7 @@ const getNamesAndTypes = (
   const firstName = rawNames[0]
   if (rawNames.length > 1 || (firstName && !isValidVariableName(firstName))) {
     const aliasType = rawNames.join(' | ')
-    const aliasName =
-      funcName.charAt(0).toUpperCase() + funcName.slice(1) + direction
+    const aliasName = funcIdToTypeName(funcName) + direction
 
     // record the alias in your TypesMap
     const references = rawTypes
@@ -246,7 +259,6 @@ const isPrimitiveType = (type: ts.Type): boolean => {
     ts.TypeFlags.Void |
     ts.TypeFlags.Undefined |
     ts.TypeFlags.Null |
-    ts.TypeFlags.Any |
     ts.TypeFlags.Unknown |
     ts.TypeFlags.VoidLike
 
@@ -280,7 +292,13 @@ function unwrapPromise(checker: ts.TypeChecker, type: ts.Type): ts.Type {
  * Inspect pikkuFunc calls, extract input/output and first-arg destructuring,
  * then push into state.functions.meta.
  */
-export const addFunctions: AddWiring = (logger, node, checker, state) => {
+export const addFunctions: AddWiring = (
+  logger,
+  node,
+  checker,
+  state,
+  options
+) => {
   if (!ts.isCallExpression(node)) return
 
   const { expression, arguments: args, typeArguments } = node
@@ -303,16 +321,31 @@ export const addFunctions: AddWiring = (logger, node, checker, state) => {
 
   if (args.length === 0) return
 
-  const { pikkuFuncName, name, explicitName, exportedName } =
-    extractFunctionName(node, checker, state.rootDir)
+  let { pikkuFuncId, name, explicitName, exportedName } = extractFunctionName(
+    node,
+    checker,
+    state.rootDir
+  )
+
+  if (!pikkuFuncId || pikkuFuncId.startsWith('__temp_')) {
+    return
+  }
 
+  let title: string | undefined
   let tags: string[] | undefined
   let summary: string | undefined
   let description: string | undefined
   let errors: string[] | undefined
   let expose: boolean | undefined
-  let internal: boolean | undefined
+  let remote: boolean | undefined
+  let mcp: boolean | undefined
+  let requiresApproval: boolean | undefined
+  let version: number | undefined
   let objectNode: ts.ObjectLiteralExpression | undefined
+  let nodeDisplayName: string | null = null
+  let nodeCategory: string | null = null
+  let nodeType: NodeType | null = null
+  let nodeErrorOutput: boolean | null = null
 
   // Extract the function node using shared utility
   const firstArg = args[0]!
@@ -322,18 +355,168 @@ export const addFunctions: AddWiring = (logger, node, checker, state) => {
     isDirectFunction,
   } = extractFunctionNode(firstArg, checker)
 
+  // Variables to hold schema references if provided
+  let inputSchemaRef: SchemaRef | null = null
+  let outputSchemaRef: SchemaRef | null = null
+
+  // Helper to resolve schema identifier to its actual source file and detect vendor.
+  // Logs a fatal error and returns null if vendor cannot be determined.
+  const resolveSchemaRef = (
+    identifier: ts.Identifier,
+    context: string
+  ): SchemaRef | null => {
+    const symbol = checker.getSymbolAtLocation(identifier)
+    if (!symbol) return null
+
+    const decl = symbol.valueDeclaration || symbol.declarations?.[0]
+    if (!decl) return null
+
+    let sourceFile: string
+
+    // If it's an import specifier, resolve the aliased symbol to get the actual source
+    if (ts.isImportSpecifier(decl)) {
+      const aliasedSymbol = checker.getAliasedSymbol(symbol)
+      if (aliasedSymbol) {
+        const aliasedDecl =
+          aliasedSymbol.valueDeclaration || aliasedSymbol.declarations?.[0]
+        if (aliasedDecl) {
+          sourceFile = aliasedDecl.getSourceFile().fileName
+        } else {
+          return null
+        }
+      } else {
+        return null
+      }
+    } else {
+      sourceFile = decl.getSourceFile().fileName
+    }
+
+    const vendor = detectSchemaVendorOrError(
+      identifier,
+      checker,
+      logger,
+      context,
+      sourceFile
+    )
+    if (!vendor) return null
+
+    return {
+      variableName: identifier.text,
+      sourceFile,
+      vendor,
+    }
+  }
+
   // Extract config properties if using object form
   if (ts.isObjectLiteralExpression(firstArg)) {
     objectNode = firstArg
     const metadata = getCommonWireMetaData(firstArg, 'Function', name, logger)
+    if (metadata.disabled) return
+    title = metadata.title
     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
+    remote = getPropertyValue(firstArg, 'remote') as boolean | undefined
+    mcp = getPropertyValue(firstArg, 'mcp') as boolean | undefined
+    requiresApproval = getPropertyValue(firstArg, 'requiresApproval') as
+      | boolean
+      | undefined
+
+    const versionRaw = getPropertyValue(firstArg, 'version')
+    if (versionRaw !== null && versionRaw !== undefined) {
+      const parsed = Number(versionRaw)
+      if (Number.isInteger(parsed) && parsed >= 1) {
+        version = parsed
+      }
+    }
+
+    // Extract node config from nested object
+    for (const prop of firstArg.properties) {
+      if (
+        ts.isPropertyAssignment(prop) &&
+        ts.isIdentifier(prop.name) &&
+        prop.name.text === 'node' &&
+        ts.isObjectLiteralExpression(prop.initializer)
+      ) {
+        const nodeObj = prop.initializer
+        nodeDisplayName = getPropertyValue(nodeObj, 'displayName') as
+          | string
+          | null
+        nodeCategory = getPropertyValue(nodeObj, 'category') as string | null
+        nodeType = getPropertyValue(nodeObj, 'type') as NodeType | null
+        nodeErrorOutput = getPropertyValue(nodeObj, 'errorOutput') as
+          | boolean
+          | null
+
+        if (!nodeDisplayName) {
+          logger.critical(
+            ErrorCode.MISSING_NAME,
+            `Function '${name}' node config is missing the required 'displayName' property.`
+          )
+        }
+        if (!nodeCategory) {
+          logger.critical(
+            ErrorCode.MISSING_NAME,
+            `Function '${name}' node config is missing the required 'category' property.`
+          )
+        }
+        if (!nodeType) {
+          logger.critical(
+            ErrorCode.MISSING_NAME,
+            `Function '${name}' node config is missing the required 'type' property.`
+          )
+        } else if (!['trigger', 'action', 'end'].includes(nodeType)) {
+          logger.critical(
+            ErrorCode.INVALID_VALUE,
+            `Function '${name}' node config has invalid type '${nodeType}'. Must be 'trigger', 'action', or 'end'.`
+          )
+        }
+        break
+      }
+    }
+
+    // Extract schema variable names from input/output properties
+    for (const prop of firstArg.properties) {
+      if (ts.isPropertyAssignment(prop) && ts.isIdentifier(prop.name)) {
+        const propName = prop.name.text
+        if (propName === 'input' || propName === 'output') {
+          if (ts.isIdentifier(prop.initializer)) {
+            // Good - it's a variable reference, resolve its actual source file and vendor
+            const context = `Function '${name}' ${propName}`
+            const ref = resolveSchemaRef(prop.initializer, context)
+            if (ref) {
+              if (propName === 'input') {
+                inputSchemaRef = ref
+              } else {
+                outputSchemaRef = ref
+              }
+            }
+          } else if (ts.isCallExpression(prop.initializer)) {
+            // Bad - it's an inline expression
+            const schemaName = `${funcIdToTypeName(name)}${propName.charAt(0).toUpperCase() + propName.slice(1)}`
+            logger.critical(
+              ErrorCode.INLINE_SCHEMA,
+              `Inline schemas are not supported for '${propName}' in '${name}'.\n` +
+                `  Extract to an exported variable:\n` +
+                `    export const ${schemaName} = ${prop.initializer.getText()}\n` +
+                `  Then use: ${propName}: ${schemaName}`
+            )
+          }
+        }
+      }
+    }
   }
 
+  if (version !== undefined) {
+    const baseName = explicitName || exportedName || pikkuFuncId
+    pikkuFuncId = formatVersionedId(baseName, version)
+  }
+
+  const isMCPToolFunc = expression.text === 'pikkuMCPToolFunc'
+  const mcpEnabled = mcp || isMCPToolFunc
+
   // Pick the handler: use resolvedFunc when it exists and is a function, otherwise fall back to handlerNode
   const handler =
     resolvedFunc &&
@@ -343,10 +526,11 @@ export const addFunctions: AddWiring = (logger, node, checker, state) => {
 
   // Validate that we got a valid function
   if (!ts.isArrowFunction(handler) && !ts.isFunctionExpression(handler)) {
-    logger.error(`• No valid 'func' property found for ${pikkuFuncName}.`)
+    logger.error(`• No valid 'func' property found for ${pikkuFuncId}.`)
     // Create stub metadata to prevent "function not found" errors in wirings
-    state.functions.meta[pikkuFuncName] = {
-      pikkuFuncName,
+    state.functions.meta[pikkuFuncId] = {
+      pikkuFuncId,
+      functionType: 'user',
       name,
       services: { optimized: false, services: [] },
       inputSchemaName: null,
@@ -377,50 +561,69 @@ export const addFunctions: AddWiring = (logger, node, checker, state) => {
           services.services.push(original)
         }
       }
-    } else if (ts.isIdentifier(firstParam.name)) {
+    } else if (
+      ts.isIdentifier(firstParam.name) &&
+      !firstParam.name.text.startsWith('_')
+    ) {
       services.optimized = false
     }
   }
 
-  // --- 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)
-      }
-    }
-  }
+  const wires = extractUsedWires(handler, 2)
 
   // --- Generics → ts.Type[], unwrapped from Promise ---
   const genericTypes: ts.Type[] = (typeArguments ?? [])
     .map((tn) => checker.getTypeFromTypeNode(tn))
     .map((t) => unwrapPromise(checker, t))
 
+  const capitalizedName = funcIdToTypeName(name)
+
   // --- Input Extraction ---
-  let { names: inputNames, types: inputTypes } = getNamesAndTypes(
-    checker,
-    state.functions.typesMap,
-    'Input',
-    name,
-    genericTypes[0]
-  )
-  // if (inputTypes.length === 0) {
-  //   logger.debug(
-  //     `\x1b[31m• Unknown input type for '${name}', assuming void.\x1b[0m`
-  //   )
-  // }
+  let inputNames: string[] = []
+  let inputTypes: ts.Type[] = []
+
+  if (inputSchemaRef) {
+    const schemaName = `${capitalizedName}Input`
+    inputNames = [schemaName]
+    state.schemaLookup.set(schemaName, inputSchemaRef)
+    state.functions.typesMap.addCustomType(schemaName, 'unknown', [])
+  } else if (genericTypes.length >= 1 && genericTypes[0]) {
+    // Fall back to extracting from generic type arguments
+    const result = getNamesAndTypes(
+      checker,
+      state.functions.typesMap,
+      'Input',
+      name,
+      genericTypes[0]
+    )
+    inputNames = result.names
+    inputTypes = result.types
+  } else {
+    // Fall back to extracting from the function's second parameter type
+    const secondParam = handler.parameters[1]
+    if (secondParam) {
+      const paramType = checker.getTypeAtLocation(secondParam)
+      const result = getNamesAndTypes(
+        checker,
+        state.functions.typesMap,
+        'Input',
+        pikkuFuncId,
+        paramType
+      )
+      inputNames = result.names
+      inputTypes = result.types
+    }
+  }
 
   // --- Output Extraction ---
   let outputNames: string[] = []
-  if (genericTypes.length >= 2) {
+
+  if (outputSchemaRef) {
+    const schemaName = `${capitalizedName}Output`
+    outputNames = [schemaName]
+    state.schemaLookup.set(schemaName, outputSchemaRef)
+    state.functions.typesMap.addCustomType(schemaName, 'unknown', [])
+  } else if (genericTypes.length >= 2) {
     outputNames = getNamesAndTypes(
       checker,
       state.functions.typesMap,
@@ -437,12 +640,55 @@ export const addFunctions: AddWiring = (logger, node, checker, state) => {
         checker,
         state.functions.typesMap,
         'Output',
-        pikkuFuncName,
+        pikkuFuncId,
         unwrapped
       ).names
     }
   }
 
+  const mcpOutputTypes: Record<string, string> = {
+    pikkuMCPResourceFunc: 'MCPResourceResponse',
+    pikkuMCPToolFunc: 'MCPToolResponse',
+    pikkuMCPPromptFunc: 'MCPPromptResponse',
+  }
+  const mcpOutputType = mcpOutputTypes[expression.text]
+  if (mcpOutputType && outputNames[0] !== mcpOutputType) {
+    let resolved = false
+    const rawSymbol = checker.getSymbolAtLocation(expression)
+    const funcSymbol =
+      rawSymbol && rawSymbol.flags & ts.SymbolFlags.Alias
+        ? checker.getAliasedSymbol(rawSymbol)
+        : rawSymbol
+    const funcDecls = funcSymbol?.getDeclarations() || []
+    for (const funcDecl of funcDecls) {
+      if (resolved) break
+      const mcpTypeSymbol = checker.resolveName(
+        mcpOutputType,
+        funcDecl,
+        ts.SymbolFlags.Type,
+        false
+      )
+      if (mcpTypeSymbol) {
+        const aliased =
+          mcpTypeSymbol.flags & ts.SymbolFlags.Alias
+            ? checker.getAliasedSymbol(mcpTypeSymbol)
+            : mcpTypeSymbol
+        const typeDecl = aliased?.getDeclarations()?.[0]
+        if (typeDecl) {
+          const path = typeDecl.getSourceFile().fileName
+          if (!state.functions.typesMap.exists(mcpOutputType, path)) {
+            state.functions.typesMap.addType(mcpOutputType, path)
+          }
+          resolved = true
+        }
+      }
+    }
+    if (!resolved) {
+      state.functions.typesMap.addCustomType(mcpOutputType, mcpOutputType, [])
+    }
+    outputNames = [mcpOutputType]
+  }
+
   if (inputNames.length > 1) {
     logger.warn(
       'More than one input type detected, only the first one will be used as a schema.'
@@ -451,47 +697,150 @@ export const addFunctions: AddWiring = (logger, node, checker, state) => {
 
   // Store the input type for later use
   if (inputTypes.length > 0) {
-    state.typesLookup.set(pikkuFuncName, inputTypes)
+    state.typesLookup.set(pikkuFuncId, inputTypes)
   }
 
   // --- resolve middleware ---
-  const middleware = objectNode
+  let middleware = objectNode
     ? resolveMiddleware(state, objectNode, tags, checker)
     : undefined
 
-  state.functions.meta[pikkuFuncName] = {
-    pikkuFuncName,
+  // --- resolve permissions ---
+  let permissions = objectNode
+    ? resolvePermissions(state, objectNode, tags, checker)
+    : undefined
+
+  if (options.tags?.length) {
+    tags = [...new Set([...(tags || []), ...options.tags])]
+    const tagEntries = options.tags.map((tag) => ({
+      type: 'tag' as const,
+      tag,
+    }))
+    const existingMiddlewareTags = new Set(
+      (middleware || [])
+        .filter((m) => m.type === 'tag')
+        .map((m) => (m as any).tag)
+    )
+    const newMiddleware = tagEntries.filter(
+      (e) => !existingMiddlewareTags.has(e.tag)
+    )
+    if (newMiddleware.length > 0) {
+      middleware = [...(middleware || []), ...newMiddleware]
+    }
+    const existingPermissionTags = new Set(
+      (permissions || [])
+        .filter((p) => p.type === 'tag')
+        .map((p) => (p as any).tag)
+    )
+    const newPermissions = tagEntries.filter(
+      (e) => !existingPermissionTags.has(e.tag)
+    )
+    if (newPermissions.length > 0) {
+      permissions = [...(permissions || []), ...newPermissions]
+    }
+  }
+
+  const sessionless = expression.text !== 'pikkuFunc'
+
+  state.functions.meta[pikkuFuncId] = {
+    pikkuFuncId,
+    functionType: 'user',
+    funcWrapper: expression.text,
+    sessionless,
     name,
     services,
-    usedWires: usedWires.length > 0 ? usedWires : undefined,
+    wires: wires.wires.length > 0 || !wires.optimized ? wires : 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,
+    remote: remote || undefined,
+    mcp: mcpEnabled || undefined,
+    requiresApproval: requiresApproval || undefined,
+    version,
+    title,
     tags: tags || undefined,
     summary,
     description,
     errors,
     middleware,
+    permissions,
     isDirectFunction,
   }
 
-  // Store function file location for wiring generation
-  if (exportedName) {
-    state.functions.files.set(pikkuFuncName, {
-      path: node.getSourceFile().fileName,
-      exportedName,
-    })
+  // Populate node metadata if node config is present
+  if (nodeDisplayName && nodeCategory && nodeType) {
+    state.nodes.files.add(node.getSourceFile().fileName)
+    state.nodes.meta[pikkuFuncId] = {
+      name: pikkuFuncId,
+      displayName: nodeDisplayName,
+      category: nodeCategory,
+      type: nodeType,
+      rpc: pikkuFuncId,
+      description,
+      errorOutput: nodeErrorOutput ?? false,
+      inputSchemaName: inputNames[0] ?? null,
+      outputSchemaName: outputNames[0] ?? null,
+      tags,
+    }
+  }
+
+  if (mcpEnabled) {
+    if (!description) {
+      logger.critical(
+        ErrorCode.MISSING_DESCRIPTION,
+        `MCP tool '${name}' is missing a description.`
+      )
+      return
+    }
+    state.mcpEndpoints.files.add(node.getSourceFile().fileName)
+    state.mcpEndpoints.toolsMeta[name] = {
+      pikkuFuncId,
+      name,
+      title: title || undefined,
+      description,
+      summary,
+      errors,
+      tags,
+      inputSchema: inputNames[0] ?? null,
+      outputSchema: outputNames[0] ?? null,
+      middleware,
+      permissions,
+    }
+    state.serviceAggregation.usedFunctions.add(pikkuFuncId)
+    extractWireNames(middleware).forEach((n) =>
+      state.serviceAggregation.usedMiddleware.add(n)
+    )
+    extractWireNames(permissions).forEach((n) =>
+      state.serviceAggregation.usedPermissions.add(n)
+    )
   }
 
   // Workflow functions don't get registered as RPC functions,
-  // they are their own type handled by add-workdflow
+  // they are their own type handled by add-workflow
   if (expression.text.includes('Workflow')) {
     return
   }
 
+  // Trigger and channel connect/disconnect functions are not callable via RPC
+  const nonRPCPatterns = [
+    /Trigger/i,
+    /ChannelConnection/i,
+    /ChannelDisconnection/i,
+  ]
+  if (nonRPCPatterns.some((pattern) => pattern.test(expression.text))) {
+    return
+  }
+
+  // Store function file location for wiring generation
+  if (exportedName) {
+    state.functions.files.set(pikkuFuncId, {
+      path: node.getSourceFile().fileName,
+      exportedName,
+    })
+  }
+
   if (exportedName || explicitName) {
     if (!exportedName) {
       logger.error(
@@ -500,28 +849,37 @@ 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 (remote) {
+      state.rpc.invokedFunctions.add(pikkuFuncId)
     }
 
     if (expose) {
-      state.rpc.exposedMeta[name] = pikkuFuncName
+      state.rpc.exposedMeta[name] = pikkuFuncId
       state.rpc.exposedFiles.set(name, {
         path: node.getSourceFile().fileName,
         exportedName,
       })
       // Track exposed RPC function for service aggregation
-      state.serviceAggregation.usedFunctions.add(pikkuFuncName)
+      state.serviceAggregation.usedFunctions.add(pikkuFuncId)
     }
 
     // We add it to internal meta to allow autocomplete for everything
-    state.rpc.internalMeta[name] = pikkuFuncName
+    state.rpc.internalMeta[name] = pikkuFuncId
+
+    if (version !== undefined) {
+      state.rpc.internalMeta[pikkuFuncId] = pikkuFuncId
+      state.rpc.invokedFunctions.add(pikkuFuncId)
+    }
 
     // But we only import the actual function if it's actually invoked to keep
     // bundle size down
-    if (state.rpc.invokedFunctions.has(pikkuFuncName) || expose || internal) {
-      state.rpc.internalFiles.set(pikkuFuncName, {
+    if (
+      state.rpc.invokedFunctions.has(pikkuFuncId) ||
+      expose ||
+      remote ||
+      mcpEnabled
+    ) {
+      state.rpc.internalFiles.set(pikkuFuncId, {
         path: node.getSourceFile().fileName,
         exportedName,
       })