@pikku/inspector 0.11.1 → 0.11.2

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

@@ -9,6 +9,8 @@ import {
   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_$]*$/
@@ -152,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)
@@ -306,6 +312,7 @@ 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
@@ -322,16 +329,85 @@ export const addFunctions: AddWiring = (logger, node, checker, state) => {
     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,
+          }
+        }
+      }
+    }
+
+    // Not an import - use the current source file
+    return {
+      variableName: identifier.text,
+      sourceFile: decl.getSourceFile().fileName,
+    }
+  }
+
   // 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
@@ -404,23 +480,54 @@ export const addFunctions: AddWiring = (logger, node, checker, state) => {
     .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,
@@ -459,6 +566,11 @@ export const addFunctions: AddWiring = (logger, node, checker, state) => {
     ? resolveMiddleware(state, objectNode, tags, checker)
     : undefined
 
+  // --- resolve permissions ---
+  const permissions = objectNode
+    ? resolvePermissions(state, objectNode, tags, checker)
+    : undefined
+
   state.functions.meta[pikkuFuncName] = {
     pikkuFuncName,
     name,
@@ -470,11 +582,13 @@ export const addFunctions: AddWiring = (logger, node, checker, state) => {
     outputs: outputNames.filter((n) => n !== 'void') ?? null,
     expose: expose || undefined,
     internal: internal || undefined,
+    title,
     tags: tags || undefined,
     summary,
     description,
     errors,
     middleware,
+    permissions,
     isDirectFunction,
   }
 

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

@@ -70,7 +70,7 @@ export const addHTTPRoute: AddWiring = (
 
   const method =
     (getPropertyValue(obj, 'method') as string)?.toLowerCase() || 'get'
-  const { tags, summary, description, errors } = getCommonWireMetaData(
+  const { title, tags, summary, description, errors } = getCommonWireMetaData(
     obj,
     'HTTP route',
     route,
@@ -78,6 +78,29 @@ export const addHTTPRoute: AddWiring = (
   )
   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,
@@ -158,6 +181,7 @@ export const addHTTPRoute: AddWiring = (
     params: params.length > 0 ? params : undefined,
     query: query.length > 0 ? query : undefined,
     inputTypes,
+    title,
     summary,
     description,
     errors,

package/src/add/add-rpc-invocations.ts

@@ -1,48 +1,78 @@
 import * as ts from 'typescript'
 import { InspectorState, InspectorLogger } from '../types.js'
 
+/**
+ * Helper to extract namespace from a namespaced function reference like 'ext:hello'
+ */
+function extractNamespace(functionRef: string): string | null {
+  const colonIndex = functionRef.indexOf(':')
+  if (colonIndex !== -1) {
+    return functionRef.substring(0, colonIndex)
+  }
+  return null
+}
+
 /**
  * Scan for rpc.invoke() calls to track which functions are actually being invoked
+ * Also detects external package usage via:
+ * - Namespaced calls: rpc.invoke('namespace:function')
+ * - External helper: external('namespace:function')
  */
 export function addRPCInvocations(
   node: ts.Node,
   state: InspectorState,
   logger: InspectorLogger
 ) {
-  // Look for property access expressions: rpc.invoke
-  if (ts.isPropertyAccessExpression(node)) {
-    const { expression, name } = node
+  // Look for call expressions: external('ext:hello') or rpc.invoke('...')
+  if (ts.isCallExpression(node)) {
+    const { expression, arguments: args } = node
+
+    // Check for external('namespace:function') calls
+    if (ts.isIdentifier(expression) && expression.text === 'external') {
+      const [firstArg] = args
+      if (firstArg && ts.isStringLiteral(firstArg)) {
+        const functionRef = firstArg.text
+        logger.debug(`• Found external() call: ${functionRef}`)
+        state.rpc.invokedFunctions.add(functionRef)
 
-    // Check if this is accessing 'invoke' property
-    if (name.text === 'invoke') {
-      // Check if the object is 'rpc' (or a variable containing rpc)
-      if (ts.isIdentifier(expression) && expression.text === 'rpc') {
-        // This is rpc.invoke - now we need to find the parent call expression
-        const parent = node.parent
-        if (ts.isCallExpression(parent) && parent.expression === node) {
-          // This is rpc.invoke('function-name')
-          const [firstArg] = parent.arguments
-          if (firstArg) {
-            // Extract the function name from string literal
-            if (ts.isStringLiteral(firstArg)) {
-              const functionName = firstArg.text
-              logger.debug(`• Found RPC invocation: ${functionName}`)
-              state.rpc.invokedFunctions.add(functionName)
-            }
-            // Handle template literals like `function-${name}`
-            else if (
-              ts.isTemplateExpression(firstArg) ||
-              ts.isNoSubstitutionTemplateLiteral(firstArg)
-            ) {
-              logger.warn(
-                `• Found dynamic RPC invocation: ${firstArg.getText()}`
-              )
-              logger.warn(
-                `\tYou can only use string literals for RPC function names, with ' or " and not \``
-              )
-            }
+        const namespace = extractNamespace(functionRef)
+        if (namespace) {
+          logger.debug(`  → External package detected: ${namespace}`)
+          state.rpc.usedExternalPackages.add(namespace)
+        }
+      }
+    }
+
+    // Check for rpc.invoke('...') calls
+    if (
+      ts.isPropertyAccessExpression(expression) &&
+      expression.name.text === 'invoke' &&
+      ts.isIdentifier(expression.expression) &&
+      expression.expression.text === 'rpc'
+    ) {
+      const [firstArg] = args
+      if (firstArg) {
+        if (ts.isStringLiteral(firstArg)) {
+          const functionRef = firstArg.text
+          logger.debug(`• Found RPC invocation: ${functionRef}`)
+          state.rpc.invokedFunctions.add(functionRef)
+
+          const namespace = extractNamespace(functionRef)
+          if (namespace) {
+            logger.debug(`  → External package detected: ${namespace}`)
+            state.rpc.usedExternalPackages.add(namespace)
           }
         }
+        // Handle template literals like `function-${name}`
+        else if (
+          ts.isTemplateExpression(firstArg) ||
+          ts.isNoSubstitutionTemplateLiteral(firstArg)
+        ) {
+          logger.warn(`• Found dynamic RPC invocation: ${firstArg.getText()}`)
+          logger.warn(
+            `\tYou can only use string literals for RPC function names, with ' or " and not \``
+          )
+        }
       }
     }
   }