@pikku/inspector 0.11.0 → 0.11.2

package/src/add/add-forge-credential.ts

@@ -0,0 +1,119 @@
+import * as ts from 'typescript'
+import { getPropertyValue } from '../utils/get-property-value.js'
+import { AddWiring } from '../types.js'
+import { ErrorCode } from '../error-codes.js'
+
+/**
+ * Inspector for wireForgeCredential calls.
+ * Extracts metadata for Forge package credential declarations.
+ * Note: wireForgeCredential is metadata-only - no runtime behavior.
+ * Schema is stored as the variable name reference; actual Zod→JSON Schema conversion happens at CLI build time.
+ */
+export const addForgeCredential: 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 wireForgeCredential
+  if (
+    !ts.isIdentifier(expression) ||
+    expression.text !== 'wireForgeCredential'
+  ) {
+    return
+  }
+
+  if (!firstArg) {
+    return
+  }
+
+  if (ts.isObjectLiteralExpression(firstArg)) {
+    const obj = firstArg
+
+    const nameValue = getPropertyValue(obj, 'name') as string | null
+    const displayNameValue = getPropertyValue(obj, 'displayName') as
+      | string
+      | null
+    const descriptionValue = getPropertyValue(obj, 'description') as
+      | string
+      | null
+    const secretIdValue = getPropertyValue(obj, 'secretId') as string | null
+
+    // Get schema variable name for later runtime import
+    let schemaVariableName: string | null = null
+    for (const prop of obj.properties) {
+      if (
+        ts.isPropertyAssignment(prop) &&
+        ts.isIdentifier(prop.name) &&
+        prop.name.text === 'schema'
+      ) {
+        if (ts.isIdentifier(prop.initializer)) {
+          schemaVariableName = prop.initializer.text
+        }
+        break
+      }
+    }
+
+    // Validate required fields
+    if (!nameValue) {
+      logger.critical(
+        ErrorCode.MISSING_NAME,
+        "Forge credential is missing the required 'name' property."
+      )
+      return
+    }
+
+    if (!displayNameValue) {
+      logger.critical(
+        ErrorCode.MISSING_NAME,
+        `Forge credential '${nameValue}' is missing the required 'displayName' property.`
+      )
+      return
+    }
+
+    if (!secretIdValue) {
+      logger.critical(
+        ErrorCode.MISSING_NAME,
+        `Forge credential '${nameValue}' is missing the required 'secretId' property.`
+      )
+      return
+    }
+
+    if (!schemaVariableName) {
+      logger.critical(
+        ErrorCode.MISSING_NAME,
+        `Forge credential '${nameValue}' is missing the required 'schema' property or schema is not a variable reference.`
+      )
+      return
+    }
+
+    const sourceFile = node.getSourceFile().fileName
+
+    state.forgeCredentials.files.add(sourceFile)
+
+    // Register the zod schema in the central zodLookup for deferred conversion
+    const schemaLookupName = `ForgeCredential_${nameValue}`
+    state.zodLookup.set(schemaLookupName, {
+      variableName: schemaVariableName,
+      sourceFile,
+    })
+
+    // Store metadata - schema conversion happens later in schema-generator
+    state.forgeCredentials.meta[nameValue] = {
+      name: nameValue,
+      displayName: displayNameValue,
+      description: descriptionValue || undefined,
+      secretId: secretIdValue,
+      schema: schemaLookupName,
+    }
+  }
+}

package/src/add/add-forge-node.ts

@@ -0,0 +1,132 @@
+import * as ts from 'typescript'
+import {
+  getPropertyValue,
+  getCommonWireMetaData,
+} from '../utils/get-property-value.js'
+import { AddWiring } from '../types.js'
+import { ErrorCode } from '../error-codes.js'
+import type { ForgeNodeType } from '@pikku/core/forge-node'
+
+/**
+ * Inspector for wireForgeNode calls.
+ * Extracts metadata for Forge workflow builder nodes.
+ * Note: wireForgeNode is metadata-only - no runtime behavior.
+ */
+export const addForgeNode: 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 wireForgeNode
+  if (!ts.isIdentifier(expression) || expression.text !== 'wireForgeNode') {
+    return
+  }
+
+  if (!firstArg) {
+    return
+  }
+
+  if (ts.isObjectLiteralExpression(firstArg)) {
+    const obj = firstArg
+
+    const nameValue = getPropertyValue(obj, 'name') as string | null
+    const displayNameValue = getPropertyValue(obj, 'displayName') as
+      | string
+      | null
+    const categoryValue = getPropertyValue(obj, 'category') as string | null
+    const typeValue = getPropertyValue(obj, 'type') as ForgeNodeType | null
+    const rpcValue = getPropertyValue(obj, 'rpc') as string | null
+    const errorOutputValue = getPropertyValue(obj, 'errorOutput') as
+      | boolean
+      | null
+
+    const { tags, description } = getCommonWireMetaData(
+      obj,
+      'Forge node',
+      nameValue,
+      logger
+    )
+
+    // Validate required fields
+    if (!nameValue) {
+      logger.critical(
+        ErrorCode.MISSING_NAME,
+        "Forge node is missing the required 'name' property."
+      )
+      return
+    }
+
+    if (!displayNameValue) {
+      logger.critical(
+        ErrorCode.MISSING_NAME,
+        `Forge node '${nameValue}' is missing the required 'displayName' property.`
+      )
+      return
+    }
+
+    if (!categoryValue) {
+      logger.critical(
+        ErrorCode.MISSING_NAME,
+        `Forge node '${nameValue}' is missing the required 'category' property.`
+      )
+      return
+    }
+
+    if (!typeValue) {
+      logger.critical(
+        ErrorCode.MISSING_NAME,
+        `Forge node '${nameValue}' is missing the required 'type' property.`
+      )
+      return
+    }
+
+    if (!['trigger', 'action', 'end'].includes(typeValue)) {
+      logger.critical(
+        ErrorCode.INVALID_VALUE,
+        `Forge node '${nameValue}' has invalid type '${typeValue}'. Must be 'trigger', 'action', or 'end'.`
+      )
+      return
+    }
+
+    if (!rpcValue) {
+      logger.critical(
+        ErrorCode.MISSING_NAME,
+        `Forge node '${nameValue}' is missing the required 'rpc' property.`
+      )
+      return
+    }
+
+    // Get function metadata for input/output schemas
+    const fnMeta = state.functions.meta[rpcValue]
+    const inputSchemaName = fnMeta?.inputs?.[0] || null
+    const outputSchemaName = fnMeta?.outputs?.[0] || null
+
+    // Note: Category validation against forge.node.categories config
+    // is done at CLI build time, not during inspection
+
+    state.forgeNodes.files.add(node.getSourceFile().fileName)
+
+    state.forgeNodes.meta[nameValue] = {
+      name: nameValue,
+      displayName: displayNameValue,
+      category: categoryValue,
+      type: typeValue,
+      rpc: rpcValue,
+      description,
+      errorOutput: errorOutputValue ?? false,
+      inputSchemaName,
+      outputSchemaName,
+      tags,
+    }
+  }
+}

package/src/add/add-functions.ts

@@ -2,10 +2,15 @@ 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'
+import { resolvePermissions } from '../utils/permissions.js'
+import { ErrorCode } from '../error-codes.js'
 
 const isValidVariableName = (name: string) => {
   const regex = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/
@@ -149,14 +154,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)
@@ -303,57 +312,114 @@ export const addFunctions: AddWiring = (logger, node, checker, state) => {
   const { pikkuFuncName, name, explicitName, exportedName } =
     extractFunctionName(node, checker, state.rootDir)
 
+  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 docs: PikkuDocs | 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
-    internal = getPropertyValue(handlerNode, 'internal') 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,
+  // Extract the function node using shared utility
+  const firstArg = args[0]!
+  const {
+    funcNode: handlerNode,
+    resolvedFunc,
+    isDirectFunction,
+  } = extractFunctionNode(firstArg, checker)
+
+  // Variables to hold zod schema references if provided
+  let inputZodSchemaRef: { variableName: string; sourceFile: string } | null =
+    null
+  let outputZodSchemaRef: { variableName: string; sourceFile: string } | null =
+    null
+
+  // Helper to resolve schema identifier to its actual source file
+  const resolveSchemaSourceFile = (
+    identifier: ts.Identifier
+  ): { variableName: string; sourceFile: string } | null => {
+    const symbol = checker.getSymbolAtLocation(identifier)
+    if (!symbol) return null
+
+    const decl = symbol.valueDeclaration || symbol.declarations?.[0]
+    if (!decl) return null
+
+    // 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) {
+          return {
+            variableName: identifier.text,
+            sourceFile: aliasedDecl.getSourceFile().fileName,
+          }
+        }
       }
-      return
     }
-    handlerNode = fnProp
+
+    // Not an import - use the current source file
+    return {
+      variableName: identifier.text,
+      sourceFile: decl.getSourceFile().fileName,
+    }
   }
 
-  if (
-    !ts.isArrowFunction(handlerNode) &&
-    !ts.isFunctionExpression(handlerNode)
-  ) {
-    logger.error(`• Handler for ${name} is not a function.`)
+  // Extract config properties if using object form
+  if (ts.isObjectLiteralExpression(firstArg)) {
+    objectNode = firstArg
+    const metadata = getCommonWireMetaData(firstArg, 'Function', name, logger)
+    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
+
+    // Extract zod 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
+            const ref = resolveSchemaSourceFile(prop.initializer)
+            if (ref) {
+              if (propName === 'input') {
+                inputZodSchemaRef = ref
+              } else {
+                outputZodSchemaRef = ref
+              }
+            }
+          } else if (ts.isCallExpression(prop.initializer)) {
+            // Bad - it's an inline expression
+            const schemaName = `${name.charAt(0).toUpperCase() + name.slice(1)}${propName.charAt(0).toUpperCase() + propName.slice(1)}`
+            logger.critical(
+              ErrorCode.INLINE_ZOD_SCHEMA,
+              `Inline Zod 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}`
+            )
+          }
+        }
+      }
+    }
+  }
+
+  // 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,
@@ -373,7 +439,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) {
@@ -392,28 +458,76 @@ 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))
     .map((t) => unwrapPromise(checker, t))
 
+  const capitalizedName = name.charAt(0).toUpperCase() + name.slice(1)
+
   // --- 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 (inputZodSchemaRef) {
+    const schemaName = `${capitalizedName}Input`
+    inputNames = [schemaName]
+    state.zodLookup.set(schemaName, inputZodSchemaRef)
+    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',
+        pikkuFuncName,
+        paramType
+      )
+      inputNames = result.names
+      inputTypes = result.types
+    }
+  }
 
   // --- Output Extraction ---
   let outputNames: string[] = []
-  if (genericTypes.length >= 2) {
+
+  if (outputZodSchemaRef) {
+    const schemaName = `${capitalizedName}Output`
+    outputNames = [schemaName]
+    state.zodLookup.set(schemaName, outputZodSchemaRef)
+    state.functions.typesMap.addCustomType(schemaName, 'unknown', [])
+  } else if (genericTypes.length >= 2) {
     outputNames = getNamesAndTypes(
       checker,
       state.functions.typesMap,
@@ -422,7 +536,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)
@@ -442,30 +556,40 @@ 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)
     : undefined
 
+  // --- resolve permissions ---
+  const permissions = objectNode
+    ? resolvePermissions(state, objectNode, tags, checker)
+    : undefined
+
   state.functions.meta[pikkuFuncName] = {
     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,
+    title,
     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)
+    permissions,
+    isDirectFunction,
   }
 
   // Store function file location for wiring generation
@@ -476,6 +600,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(

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,10 +70,37 @@ 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 { title, tags, summary, description, errors } = getCommonWireMetaData(
+    obj,
+    'HTTP route',
+    route,
+    logger
+  )
   const query = (getPropertyValue(obj, 'query') as string[]) || []
 
+  // Check if this is a workflow trigger (workflow: true)
+  const isWorkflowTrigger = getPropertyValue(obj, 'workflow') === true
+  if (isWorkflowTrigger) {
+    // Workflow triggers don't need func - they're handled by workflow-utils
+    // Just record the route for HTTP meta but skip function processing
+    state.http.files.add(node.getSourceFile().fileName)
+    state.http.meta[method][route] = {
+      pikkuFuncName: '', // No function - workflow handles it
+      route,
+      method: method as HTTPMethod,
+      params: params.length > 0 ? params : undefined,
+      query: query.length > 0 ? query : undefined,
+      inputTypes: undefined,
+      title,
+      summary,
+      description,
+      errors,
+      tags,
+      workflow: true,
+    }
+    return
+  }
+
   // --- find the referenced function name first for filtering ---
   const funcInitializer = getPropertyAssignmentInitializer(
     obj,
@@ -155,7 +181,10 @@ export const addHTTPRoute: AddWiring = (
     params: params.length > 0 ? params : undefined,
     query: query.length > 0 ? query : undefined,
     inputTypes,
-    docs,
+    title,
+    summary,
+    description,
+    errors,
     tags,
     middleware,
     permissions,