@pikku/inspector 0.12.2 → 0.12.4

package/src/add/add-permission.ts

@@ -38,13 +38,15 @@ function renameTempDefinitions(
   }
 }
 
-function isInsidePermissionFactory(node: ts.Node): boolean {
+function isInsidePermissionContainer(node: ts.Node): boolean {
   let current = node.parent
   while (current) {
     if (
       ts.isCallExpression(current) &&
       ts.isIdentifier(current.expression) &&
-      current.expression.text === 'pikkuPermissionFactory'
+      (current.expression.text === 'pikkuPermissionFactory' ||
+        current.expression.text === 'addPermission' ||
+        current.expression.text === 'addHTTPPermission')
     ) {
       return true
     }
@@ -69,7 +71,7 @@ export const addPermission: AddWiring = (logger, node, checker, state) => {
   // Handle pikkuPermission(...) - individual permission function definition
   if (expression.text === 'pikkuPermission') {
     // Skip if nested inside pikkuPermissionFactory — the factory handler extracts services itself
-    if (isInsidePermissionFactory(node)) return
+    if (isInsidePermissionContainer(node)) return
 
     const arg = args[0]
     if (!arg) return
@@ -156,7 +158,7 @@ export const addPermission: AddWiring = (logger, node, checker, state) => {
   }
 
   if (expression.text === 'pikkuAuth') {
-    if (isInsidePermissionFactory(node)) return
+    if (isInsidePermissionContainer(node)) return
 
     const arg = args[0]
     if (!arg) return
@@ -373,13 +375,10 @@ export const addPermission: AddWiring = (logger, node, checker, state) => {
       state.rootDir
     )
 
-    if (permissionNames.length === 0) {
-      logger.warn(`• addPermission('${tag}', ...) has empty permissions array`)
-      return
+    if (permissionNames.length > 0) {
+      renameTempDefinitions(state, permissionNames, 'tag', tag)
     }
 
-    renameTempDefinitions(state, permissionNames, 'tag', tag)
-
     const allServices = new Set<string>()
     for (const permissionName of permissionNames) {
       const permissionMeta = state.permissions.definitions[permissionName]
@@ -479,15 +478,10 @@ export const addPermission: AddWiring = (logger, node, checker, state) => {
       state.rootDir
     )
 
-    if (permissionNames.length === 0) {
-      logger.warn(
-        `• addHTTPPermission('${pattern}', ...) has empty permissions array`
-      )
-      return
+    if (permissionNames.length > 0) {
+      renameTempDefinitions(state, permissionNames, 'http', pattern)
     }
 
-    renameTempDefinitions(state, permissionNames, 'http', pattern)
-
     const allServices = new Set<string>()
     for (const permissionName of permissionNames) {
       const permissionMeta = state.permissions.definitions[permissionName]

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

@@ -11,6 +11,7 @@ import {
 import { getPropertyAssignmentInitializer } from '../utils/type-utils.js'
 import { resolveMiddleware } from '../utils/middleware.js'
 import { extractWireNames } from '../utils/post-process.js'
+import { resolveAddonName } from '../utils/resolve-addon-package.js'
 import { ErrorCode } from '../error-codes.js'
 
 export const addQueueWorker: AddWiring = (logger, node, checker, state) => {
@@ -65,6 +66,10 @@ export const addQueueWorker: AddWiring = (logger, node, checker, state) => {
       pikkuFuncId = makeContextBasedId('queue', name)
     }
 
+    const packageName = ts.isIdentifier(funcInitializer)
+      ? resolveAddonName(funcInitializer, checker, state.rpc.wireAddonDeclarations)
+      : null
+
     if (!name) {
       logger.critical(
         ErrorCode.MISSING_QUEUE_NAME,
@@ -85,6 +90,7 @@ export const addQueueWorker: AddWiring = (logger, node, checker, state) => {
     state.queueWorkers.files.add(node.getSourceFile().fileName)
     state.queueWorkers.meta[name] = {
       pikkuFuncId,
+      ...(packageName && { packageName }),
       name,
       summary,
       description,

package/src/add/add-schedule.ts

@@ -11,6 +11,7 @@ import {
 import { getPropertyAssignmentInitializer } from '../utils/type-utils.js'
 import { resolveMiddleware } from '../utils/middleware.js'
 import { extractWireNames } from '../utils/post-process.js'
+import { resolveAddonName } from '../utils/resolve-addon-package.js'
 
 import { ErrorCode } from '../error-codes.js'
 export const addSchedule: AddWiring = (
@@ -71,6 +72,10 @@ export const addSchedule: AddWiring = (
       pikkuFuncId = makeContextBasedId('scheduler', nameValue)
     }
 
+    const packageName = ts.isIdentifier(funcInitializer)
+      ? resolveAddonName(funcInitializer, checker, state.rpc.wireAddonDeclarations)
+      : null
+
     if (!nameValue || !scheduleValue) {
       return
     }
@@ -87,6 +92,7 @@ export const addSchedule: AddWiring = (
     state.scheduledTasks.files.add(node.getSourceFile().fileName)
     state.scheduledTasks.meta[nameValue] = {
       pikkuFuncId,
+      ...(packageName && { packageName }),
       name: nameValue,
       schedule: scheduleValue,
       summary,

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/add/add-workflow.ts

@@ -11,7 +11,10 @@ import {
   extractDescription,
   extractDuration,
 } from '../utils/extract-node-value.js'
-import { getCommonWireMetaData } from '../utils/get-property-value.js'
+import {
+  getCommonWireMetaData,
+  getPropertyValue,
+} from '../utils/get-property-value.js'
 import { extractDSLWorkflow } from '../utils/workflow/dsl/extract-dsl-workflow.js'
 
 /**
@@ -206,6 +209,7 @@ export const addWorkflow: AddWiring = (logger, node, checker, state) => {
   let summary: string | undefined
   let description: string | undefined
   let errors: string[] | undefined
+  let inline: boolean | undefined
 
   if (ts.isObjectLiteralExpression(firstArg)) {
     const metadata = getCommonWireMetaData(
@@ -219,6 +223,11 @@ export const addWorkflow: AddWiring = (logger, node, checker, state) => {
     summary = metadata.summary
     description = metadata.description
     errors = metadata.errors
+
+    const inlineProp = getPropertyValue(firstArg, 'inline')
+    if (inlineProp === true) {
+      inline = true
+    }
   }
 
   // Validate that we got a valid function
@@ -324,5 +333,6 @@ export const addWorkflow: AddWiring = (logger, node, checker, state) => {
     description,
     errors,
     tags,
+    inline,
   }
 }

package/src/error-codes.ts

@@ -66,6 +66,9 @@ export enum ErrorCode {
   MISSING_MODEL = 'PKU145',
   INVALID_MODEL = 'PKU146',
 
+  // File structure errors
+  SCHEMA_AND_WIRING_COLOCATED = 'PKU490',
+
   // Optimization diagnostics
   SERVICES_NOT_DESTRUCTURED = 'PKU410',
   WIRES_NOT_DESTRUCTURED = 'PKU411',

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

@@ -20,6 +20,7 @@ import {
   computePermissionsGroupsMeta,
   computeRequiredSchemas,
   computeDiagnostics,
+  validateSchemaWiringSeparation,
 } from './utils/post-process.js'
 import { generateOpenAPISpec } from './utils/serialize-openapi-json.js'
 import { pikkuState } from '@pikku/core/internal'
@@ -30,6 +31,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 +68,7 @@ export function getInitialInspectorState(rootDir: string): InspectorState {
       typesMap: new TypesMap(),
       meta: {},
       files: new Map(),
+      approvalDescriptions: {},
     },
     http: {
       metaInputTypes: new Map(),
@@ -197,6 +203,8 @@ export function getInitialInspectorState(rootDir: string): InspectorState {
     requiredSchemas: new Set(),
     openAPISpec: null,
     diagnostics: [],
+    addonFunctions: {},
+    program: null,
   }
 }
 
@@ -205,8 +213,7 @@ export const inspect = async (
   routeFiles: string[],
   options: InspectorOptions = {}
 ): Promise<InspectorState> => {
-  const startProgram = performance.now()
-  const program = ts.createProgram(routeFiles, {
+  const compilerOptions: ts.CompilerOptions = {
     target: ts.ScriptTarget.ESNext,
     module: ts.ModuleKind.Node16,
     skipLibCheck: true,
@@ -215,9 +222,16 @@ export const inspect = async (
     types: [],
     allowJs: false,
     checkJs: false,
-  })
+  }
+  const startProgram = performance.now()
+  const program = ts.createProgram(
+    routeFiles,
+    compilerOptions,
+    undefined, // host
+    options.oldProgram
+  )
   logger.debug(
-    `Created program in ${(performance.now() - startProgram).toFixed(2)}ms`
+    `Created program in ${(performance.now() - startProgram).toFixed(0)}ms (${routeFiles.length} files${options.oldProgram ? ', incremental' : ''})`
   )
 
   const startChecker = performance.now()
@@ -249,9 +263,12 @@ export const inspect = async (
     )
   }
   logger.debug(
-    `Visit setup phase completed in ${(performance.now() - startSetup).toFixed(2)}ms`
+    `Visit setup phase completed in ${(performance.now() - startSetup).toFixed(0)}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()
@@ -261,17 +278,21 @@ export const inspect = async (
       )
     }
     logger.debug(
-      `Visit routes phase completed in ${(performance.now() - startRoutes).toFixed(2)}ms`
+      `Visit routes phase completed in ${(performance.now() - startRoutes).toFixed(0)}ms`
     )
 
     resolveLatestVersions(state, logger)
 
     if (options.schemaConfig) {
+      const startSchemas = performance.now()
       state.schemas = await generateAllSchemas(
         logger,
         options.schemaConfig,
         state
       )
+      logger.debug(
+        `generateAllSchemas took ${(performance.now() - startSchemas).toFixed(0)}ms`
+      )
       computeContractHashes(
         state.schemas,
         state.functions.typesMap,
@@ -280,6 +301,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()
@@ -311,6 +335,7 @@ export const inspect = async (
     computeMiddlewareGroupsMeta(state)
     computePermissionsGroupsMeta(state)
     computeDiagnostics(state)
+    validateSchemaWiringSeparation(logger, state)
 
     if (options.openAPI) {
       state.openAPISpec = await generateOpenAPISpec(
@@ -329,5 +354,7 @@ export const inspect = async (
     validateVariableOverrides(logger, state)
   }
 
+  state.program = program
+
   return state
 }

package/src/types.ts

@@ -98,6 +98,7 @@ export interface InspectorFunctionState {
   typesMap: TypesMap
   meta: FunctionsMeta
   files: Map<string, { path: string; exportedName: string }>
+  approvalDescriptions: Record<string, InspectorApprovalDescriptionDefinition>
 }
 
 export interface InspectorChannelState {
@@ -140,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
@@ -216,6 +225,7 @@ export type InspectorOptions = Partial<{
   tags: string[]
   manifest: VersionManifest
   modelConfig: InspectorModelConfig
+  oldProgram: ts.Program | undefined
 }>
 
 export interface InspectorLogger {
@@ -340,6 +350,7 @@ export interface InspectorState {
       {
         package: string
         rpcEndpoint?: string
+        mcp?: boolean
         secretOverrides?: Record<string, string>
         variableOverrides?: Record<string, string>
       }
@@ -409,4 +420,6 @@ export interface InspectorState {
   requiredSchemas: Set<string>
   openAPISpec: Record<string, any> | null
   diagnostics: InspectorDiagnostic[]
+  addonFunctions: Record<string, FunctionsMeta> // namespace -> addon's function metadata
+  program: ts.Program | null // Retained for incremental re-inspection
 }

package/src/utils/custom-types-generator.ts

@@ -16,6 +16,7 @@ export function generateCustomTypes(
   requiredTypes: Set<string>
 ) {
   const typeDeclarations = Array.from(typesMap.customTypes.entries())
+    .sort(([a], [b]) => a.localeCompare(b))
     .filter(([_name, { type }]) => {
       const hasUndefinedGeneric =
         /\b(Name|In|Out|Key)\b/.test(type) && /\[.*\]/.test(type)

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
+        }
+      })
+    }
   }
 }
 
@@ -467,6 +492,65 @@ export function validateAgentOverrides(
   }
 }
 
+/**
+ * Validates that Zod schemas and wiring side-effects (wireHTTPRoutes,
+ * addPermission, addHTTPMiddleware, etc.) do not coexist in the same file.
+ *
+ * The CLI uses tsImport to extract Zod schemas at runtime, which executes
+ * all top-level code in the file. Wiring calls crash during this process
+ * because the pikku state metadata doesn't exist in the CLI context.
+ */
+export function validateSchemaWiringSeparation(
+  logger: InspectorLogger,
+  state: InspectorState
+): void {
+  // Collect files that contain schemas
+  const schemaFiles = new Set<string>()
+  for (const ref of state.schemaLookup.values()) {
+    schemaFiles.add(ref.sourceFile)
+  }
+
+  // Collect files that contain wiring side-effects
+  const wiringFiles = new Set<string>()
+
+  // HTTP route wirings
+  for (const file of state.http.files) {
+    wiringFiles.add(file)
+  }
+
+  // Permission wirings (addPermission calls)
+  for (const meta of state.permissions.tagPermissions.values()) {
+    wiringFiles.add(meta.sourceFile)
+  }
+  for (const meta of state.http.routePermissions.values()) {
+    wiringFiles.add(meta.sourceFile)
+  }
+
+  // Middleware wirings (addHTTPMiddleware calls)
+  for (const meta of state.http.routeMiddleware.values()) {
+    wiringFiles.add(meta.sourceFile)
+  }
+  for (const meta of state.middleware.tagMiddleware.values()) {
+    wiringFiles.add(meta.sourceFile)
+  }
+
+  // Check for overlap
+  for (const file of schemaFiles) {
+    if (wiringFiles.has(file)) {
+      const schemas = Array.from(state.schemaLookup.entries())
+        .filter(([, ref]) => ref.sourceFile === file)
+        .map(([name]) => name)
+
+      logger.critical(
+        ErrorCode.SCHEMA_AND_WIRING_COLOCATED,
+        `File '${file}' contains both Zod schemas (${schemas.join(', ')}) and wiring calls (wireHTTPRoutes, addPermission, etc.). ` +
+          `These must be in separate files because the CLI imports schema files at runtime, which triggers wiring side-effects that crash without server context. ` +
+          `Move the route/wiring definitions to a dedicated wiring file.`
+      )
+    }
+  }
+}
+
 export function computeDiagnostics(state: InspectorState): void {
   const diagnostics: InspectorDiagnostic[] = []
 

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]
+}