@pikku/inspector 0.12.1 → 0.12.3

package/src/add/add-wire-addon.ts

@@ -40,6 +40,7 @@ export function addWireAddon(
   let name: string | undefined
   let pkg: string | undefined
   let rpcEndpoint: string | undefined
+  let mcp: boolean | undefined
   let secretOverrides: Record<string, string> | undefined
   let variableOverrides: Record<string, string> | undefined
 
@@ -53,6 +54,12 @@ export function addWireAddon(
       pkg = prop.initializer.text
     } else if (key === 'rpcEndpoint' && ts.isStringLiteral(prop.initializer)) {
       rpcEndpoint = prop.initializer.text
+    } else if (
+      key === 'mcp' &&
+      (prop.initializer.kind === ts.SyntaxKind.TrueKeyword ||
+        prop.initializer.kind === ts.SyntaxKind.FalseKeyword)
+    ) {
+      mcp = prop.initializer.kind === ts.SyntaxKind.TrueKeyword
     } else if (
       key === 'secretOverrides' &&
       ts.isObjectLiteralExpression(prop.initializer)
@@ -72,6 +79,7 @@ export function addWireAddon(
   state.rpc.wireAddonDeclarations.set(name, {
     package: pkg,
     rpcEndpoint,
+    mcp,
     secretOverrides,
     variableOverrides,
   })

package/src/index.ts

@@ -32,6 +32,7 @@ export {
   deserializeAllDslWorkflows,
 } from './utils/workflow/dsl/index.js'
 export { getFilesAndMethods } from './utils/get-files-and-methods.js'
+export { resolveFunctionMeta } from './utils/resolve-function-meta.js'
 export type {
   SerializedWorkflowGraph,
   SerializedWorkflowGraphs,

package/src/inspector.ts

@@ -30,6 +30,10 @@ import {
   finalizeWorkflowWires,
 } from './utils/workflow/graph/finalize-workflow-wires.js'
 import { generateAllSchemas } from './utils/schema-generator.js'
+import {
+  loadAddonFunctionsMeta,
+  loadAddonSchemas,
+} from './utils/load-addon-functions-meta.js'
 import {
   computeContractHashes,
   extractContractsFromMeta,
@@ -63,6 +67,7 @@ export function getInitialInspectorState(rootDir: string): InspectorState {
       typesMap: new TypesMap(),
       meta: {},
       files: new Map(),
+      approvalDescriptions: {},
     },
     http: {
       metaInputTypes: new Map(),
@@ -83,6 +88,10 @@ export function getInitialInspectorState(rootDir: string): InspectorState {
       files: new Set(),
       meta: {},
     },
+    gateways: {
+      meta: {},
+      files: new Set(),
+    },
     triggers: {
       meta: {},
       sourceMeta: {},
@@ -193,6 +202,7 @@ export function getInitialInspectorState(rootDir: string): InspectorState {
     requiredSchemas: new Set(),
     openAPISpec: null,
     diagnostics: [],
+    addonFunctions: {},
   }
 }
 
@@ -248,6 +258,9 @@ export const inspect = async (
     `Visit setup phase completed in ${(performance.now() - startSetup).toFixed(2)}ms`
   )
 
+  // Load addon function metadata so wirings can reference addon functions
+  await loadAddonFunctionsMeta(logger, state)
+
   if (!options.setupOnly) {
     // Second sweep: add all transports
     const startRoutes = performance.now()
@@ -276,6 +289,9 @@ export const inspect = async (
       computeRequiredSchemas(state, options)
     }
 
+    // Re-load addon schemas (generateAllSchemas replaces state.schemas)
+    await loadAddonSchemas(logger, state)
+
     state.manifest.initial = options.manifest ?? null
     const contracts = extractContractsFromMeta(state.functions.meta)
     const baseManifest = state.manifest.initial ?? createEmptyManifest()

package/src/types.ts

@@ -1,5 +1,6 @@
 import type * as ts from 'typescript'
 import type { ChannelsMeta } from '@pikku/core/channel'
+import type { GatewaysMeta } from '@pikku/core/gateway'
 import type { HTTPWiringsMeta } from '@pikku/core/http'
 import type { ScheduledTasksMeta } from '@pikku/core/scheduler'
 import type { TriggerMeta, TriggerSourceMeta } from '@pikku/core/trigger'
@@ -97,6 +98,7 @@ export interface InspectorFunctionState {
   typesMap: TypesMap
   meta: FunctionsMeta
   files: Map<string, { path: string; exportedName: string }>
+  approvalDescriptions: Record<string, InspectorApprovalDescriptionDefinition>
 }
 
 export interface InspectorChannelState {
@@ -139,6 +141,14 @@ export interface InspectorAIMiddlewareState {
   definitions: Record<string, InspectorMiddlewareDefinition>
 }
 
+export interface InspectorApprovalDescriptionDefinition {
+  services: FunctionServicesMeta
+  wires?: FunctionWiresMeta
+  sourceFile: string
+  position: number
+  exportedName: string | null
+}
+
 export interface InspectorPermissionDefinition {
   services: FunctionServicesMeta
   wires?: FunctionWiresMeta
@@ -303,6 +313,10 @@ export interface InspectorState {
   http: InspectorHTTPState
   functions: InspectorFunctionState
   channels: InspectorChannelState
+  gateways: {
+    meta: GatewaysMeta
+    files: Set<string>
+  }
   triggers: {
     meta: TriggerMeta
     sourceMeta: TriggerSourceMeta
@@ -335,6 +349,7 @@ export interface InspectorState {
       {
         package: string
         rpcEndpoint?: string
+        mcp?: boolean
         secretOverrides?: Record<string, string>
         variableOverrides?: Record<string, string>
       }
@@ -404,4 +419,5 @@ export interface InspectorState {
   requiredSchemas: Set<string>
   openAPISpec: Record<string, any> | null
   diagnostics: InspectorDiagnostic[]
+  addonFunctions: Record<string, FunctionsMeta> // namespace -> addon's function metadata
 }

package/src/utils/load-addon-functions-meta.ts

@@ -0,0 +1,94 @@
+import { readFile, readdir } from 'fs/promises'
+import { createRequire } from 'module'
+import { join, dirname } from 'path'
+import type { InspectorState, InspectorLogger } from '../types.js'
+
+/**
+ * After the setup sweep discovers wireAddon() declarations, load each addon
+ * package's function metadata so that wiring handlers (channels, HTTP routes,
+ * schedules, etc.) can look up addon function types during the routes sweep.
+ */
+export async function loadAddonFunctionsMeta(
+  logger: InspectorLogger,
+  state: InspectorState
+): Promise<void> {
+  const { wireAddonDeclarations } = state.rpc
+  if (wireAddonDeclarations.size === 0) return
+
+  const require = createRequire(join(state.rootDir, 'package.json'))
+
+  for (const [namespace, decl] of wireAddonDeclarations) {
+    try {
+      const metaPath = require.resolve(
+        `${decl.package}/.pikku/function/pikku-functions-meta.gen.json`
+      )
+      const raw = await readFile(metaPath, 'utf-8')
+      const meta = JSON.parse(raw)
+      state.addonFunctions[namespace] = meta
+      logger.debug(
+        `Loaded ${Object.keys(meta).length} addon functions for '${namespace}' from ${decl.package}`
+      )
+
+      // If wireAddon has mcp: true, expose addon functions with mcp: true as MCP tools
+      if (decl.mcp) {
+        for (const [funcName, funcMeta] of Object.entries<any>(meta)) {
+          if (funcMeta.mcp) {
+            const toolName = `${namespace}:${funcName}`
+            state.mcpEndpoints.toolsMeta[toolName] = {
+              pikkuFuncId: `${namespace}:${funcName}`,
+              name: toolName,
+              description: funcMeta.description || funcMeta.title || funcName,
+              inputSchema: funcMeta.inputSchemaName ?? null,
+              outputSchema: funcMeta.outputSchemaName ?? null,
+              tags: funcMeta.tags,
+            }
+          }
+        }
+      }
+    } catch (error: any) {
+      logger.warn(
+        `Failed to load addon function metadata for '${namespace}' (${decl.package}): ${error.message}`
+      )
+    }
+  }
+}
+
+/**
+ * Load addon schemas into state.schemas. Called after generateAllSchemas
+ * to ensure addon schemas aren't overwritten.
+ */
+export async function loadAddonSchemas(
+  logger: InspectorLogger,
+  state: InspectorState
+): Promise<void> {
+  const { wireAddonDeclarations } = state.rpc
+  if (wireAddonDeclarations.size === 0) return
+
+  const require = createRequire(join(state.rootDir, 'package.json'))
+
+  for (const [namespace, decl] of wireAddonDeclarations) {
+    try {
+      const metaPath = require.resolve(
+        `${decl.package}/.pikku/function/pikku-functions-meta.gen.json`
+      )
+      const schemasDir = join(dirname(metaPath), '..', 'schemas', 'schemas')
+      try {
+        const schemaFiles = await readdir(schemasDir)
+        for (const file of schemaFiles) {
+          if (!file.endsWith('.schema.json')) continue
+          const schemaName = file.replace('.schema.json', '')
+          if (!state.schemas[schemaName]) {
+            const schemaRaw = await readFile(join(schemasDir, file), 'utf-8')
+            state.schemas[schemaName] = JSON.parse(schemaRaw)
+          }
+        }
+      } catch {
+        // No schemas directory — that's fine
+      }
+    } catch (error: any) {
+      logger.warn(
+        `Failed to load addon schemas for '${namespace}' (${decl.package}): ${error.message}`
+      )
+    }
+  }
+}

package/src/utils/post-process.ts

@@ -296,6 +296,31 @@ export function computeResolvedIOTypes(state: InspectorState): void {
     }
 
     state.resolvedIOTypes[pikkuFuncId] = { inputType, outputType }
+
+    if (meta.inputSchemaName && inputType !== 'null') {
+      meta.inputSchemaName = inputType
+    }
+    if (meta.outputSchemaName && outputType !== 'null') {
+      meta.outputSchemaName = outputType
+    }
+    if (meta.inputs) {
+      meta.inputs = meta.inputs.map((name) => {
+        try {
+          return functions.typesMap.getTypeMeta(name).uniqueName
+        } catch {
+          return name
+        }
+      })
+    }
+    if (meta.outputs) {
+      meta.outputs = meta.outputs.map((name) => {
+        try {
+          return functions.typesMap.getTypeMeta(name).uniqueName
+        } catch {
+          return name
+        }
+      })
+    }
   }
 }
 

package/src/utils/resolve-function-meta.ts

@@ -0,0 +1,25 @@
+import type { FunctionMeta, FunctionsMeta } from '@pikku/core'
+
+/**
+ * Look up function metadata by pikkuFuncId, checking both local functions
+ * and addon functions. Addon functions use namespaced IDs like 'namespace:funcName'.
+ */
+export function resolveFunctionMeta(
+  state: {
+    functions: { meta: FunctionsMeta }
+    addonFunctions: Record<string, FunctionsMeta>
+  },
+  pikkuFuncId: string
+): FunctionMeta | undefined {
+  // Check local functions first
+  const local = state.functions.meta[pikkuFuncId]
+  if (local) return local
+
+  // Check addon functions (namespaced like 'swaggerPetstore:addPet')
+  const colonIndex = pikkuFuncId.indexOf(':')
+  if (colonIndex === -1) return undefined
+
+  const namespace = pikkuFuncId.substring(0, colonIndex)
+  const funcName = pikkuFuncId.substring(colonIndex + 1)
+  return state.addonFunctions[namespace]?.[funcName]
+}

package/src/utils/serialize-inspector-state.ts

@@ -81,6 +81,7 @@ export interface SerializableInspectorState {
     }
     meta: InspectorState['functions']['meta']
     files: Array<[string, { path: string; exportedName: string }]>
+    approvalDescriptions: InspectorState['functions']['approvalDescriptions']
   }
   http: {
     metaInputTypes: Array<
@@ -116,6 +117,10 @@ export interface SerializableInspectorState {
     files: string[]
     meta: InspectorState['channels']['meta']
   }
+  gateways: {
+    meta: InspectorState['gateways']['meta']
+    files: string[]
+  }
   triggers: {
     meta: InspectorState['triggers']['meta']
     sourceMeta: InspectorState['triggers']['sourceMeta']
@@ -245,6 +250,7 @@ export interface SerializableInspectorState {
   requiredSchemas: string[]
   openAPISpec: Record<string, any> | null
   diagnostics: InspectorDiagnostic[]
+  addonFunctions: InspectorState['addonFunctions']
 }
 
 /**
@@ -303,6 +309,7 @@ export function serializeInspectorState(
       typesMap: serializeTypesMap(state.functions.typesMap),
       meta: state.functions.meta,
       files: Array.from(state.functions.files.entries()),
+      approvalDescriptions: state.functions.approvalDescriptions,
     },
     http: {
       metaInputTypes: Array.from(state.http.metaInputTypes.entries()),
@@ -315,6 +322,10 @@ export function serializeInspectorState(
       files: Array.from(state.channels.files),
       meta: state.channels.meta,
     },
+    gateways: {
+      meta: state.gateways.meta,
+      files: Array.from(state.gateways.files),
+    },
     triggers: {
       meta: state.triggers.meta,
       sourceMeta: state.triggers.sourceMeta,
@@ -408,6 +419,7 @@ export function serializeInspectorState(
     requiredSchemas: Array.from(state.requiredSchemas),
     openAPISpec: state.openAPISpec,
     diagnostics: state.diagnostics,
+    addonFunctions: state.addonFunctions,
   }
 }
 
@@ -467,6 +479,7 @@ export function deserializeInspectorState(
       typesMap: deserializeTypesMap(data.functions.typesMap),
       meta: data.functions.meta,
       files: new Map(data.functions.files),
+      approvalDescriptions: (data.functions as any).approvalDescriptions || {},
     },
     http: {
       metaInputTypes: new Map(data.http.metaInputTypes),
@@ -479,6 +492,10 @@ export function deserializeInspectorState(
       files: new Set(data.channels.files),
       meta: data.channels.meta,
     },
+    gateways: {
+      meta: data.gateways?.meta ?? {},
+      files: new Set(data.gateways?.files ?? []),
+    },
     triggers: {
       meta: data.triggers?.meta ?? {},
       sourceMeta: data.triggers?.sourceMeta ?? {},
@@ -578,5 +595,6 @@ export function deserializeInspectorState(
     requiredSchemas: new Set(data.requiredSchemas || []),
     openAPISpec: data.openAPISpec || null,
     diagnostics: data.diagnostics || [],
+    addonFunctions: data.addonFunctions || {},
   }
 }

package/src/utils/serialize-mcp-json.ts

@@ -1,5 +1,6 @@
 import type { InspectorLogger, InspectorState } from '../types.js'
 import type { JSONValue } from '@pikku/core'
+import { resolveFunctionMeta } from './resolve-function-meta.js'
 
 interface MCPEndpoint {
   uri?: string
@@ -15,7 +16,7 @@ export const serializeMCPJson = (
   state: InspectorState
 ): string => {
   const { mcpEndpoints, functions, schemas } = state
-  const { meta: functionsMeta, typesMap } = functions
+  const { typesMap } = functions
   const { resourcesMeta, toolsMeta, promptsMeta } = mcpEndpoints
 
   const tools: MCPEndpoint[] = []
@@ -39,9 +40,13 @@ export const serializeMCPJson = (
       return undefined
     }
 
-    const uniqueName = typesMap.getUniqueName(typeName)
-    if (!uniqueName) {
-      return undefined
+    // Try local typesMap first, fall back to direct schema lookup (for addon types)
+    let uniqueName: string | undefined
+    try {
+      uniqueName = typesMap.getUniqueName(typeName)
+    } catch {
+      // Type not in local typesMap — try direct schema lookup (addon schemas)
+      uniqueName = typeName
     }
 
     const schema = schemas[uniqueName]
@@ -56,7 +61,7 @@ export const serializeMCPJson = (
   }
 
   for (const [name, endpointMeta] of Object.entries(resourcesMeta)) {
-    const functionMeta = functionsMeta[endpointMeta.pikkuFuncId]
+    const functionMeta = resolveFunctionMeta(state, endpointMeta.pikkuFuncId)
     if (!functionMeta) {
       logger.warn(
         `Function ${endpointMeta.pikkuFuncId} not found in functionsMeta. Skipping resource ${name}.`
@@ -81,7 +86,7 @@ export const serializeMCPJson = (
   }
 
   for (const [name, endpointMeta] of Object.entries(toolsMeta)) {
-    const functionMeta = functionsMeta[endpointMeta.pikkuFuncId]
+    const functionMeta = resolveFunctionMeta(state, endpointMeta.pikkuFuncId)
     if (!functionMeta) {
       logger.warn(
         `Function ${endpointMeta.pikkuFuncId} not found in functionsMeta. Skipping tool ${name}.`
@@ -105,7 +110,7 @@ export const serializeMCPJson = (
   }
 
   for (const [name, endpointMeta] of Object.entries(promptsMeta)) {
-    const functionMeta = functionsMeta[endpointMeta.pikkuFuncId]
+    const functionMeta = resolveFunctionMeta(state, endpointMeta.pikkuFuncId)
     if (!functionMeta) {
       logger.warn(
         `Function ${endpointMeta.pikkuFuncId} not found in functionsMeta. Skipping prompt ${name}.`

package/src/visit.ts

@@ -16,6 +16,7 @@ import type {
 } from './types.js'
 import { addFunctions } from './add/add-functions.js'
 import { addChannel } from './add/add-channel.js'
+import { addGateway } from './add/add-gateway.js'
 import { addRPCInvocations } from './add/add-rpc-invocations.js'
 import { addWireAddon } from './add/add-wire-addon.js'
 import { addMiddleware } from './add/add-middleware.js'
@@ -25,6 +26,7 @@ import { addSecret, addOAuth2Credential } from './add/add-secret.js'
 import { addVariable } from './add/add-variable.js'
 import { addWorkflowGraph } from './add/add-workflow-graph.js'
 import { addAIAgent } from './add/add-ai-agent.js'
+import { addApprovalDescription } from './add/add-approval-description.js'
 
 export const visitSetup = (
   logger: InspectorLogger,
@@ -86,6 +88,7 @@ export const visitSetup = (
   addWireAddon(node, state, logger)
   addMiddleware(logger, node, checker, state, options)
   addPermission(logger, node, checker, state, options)
+  addApprovalDescription(logger, node, checker, state, options)
   addWorkflow(logger, node, checker, state, options)
 
   ts.forEachChild(node, (child) =>
@@ -111,6 +114,7 @@ export const visitRoutes = (
   addTrigger(logger, node, checker, state, options)
   addQueueWorker(logger, node, checker, state, options)
   addChannel(logger, node, checker, state, options)
+  addGateway(logger, node, checker, state, options)
   addCLI(logger, node, checker, state, options)
   addCLIRenderers(logger, node, checker, state, options)
   addMCPResource(logger, node, checker, state, options)