@pikku/inspector 0.7.7 → 0.8.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/inspector",
-  "version": "0.7.7",
+  "version": "0.8.1",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
   "type": "module",
@@ -17,7 +17,7 @@
     "test:coverage": "bash run-tests.sh --coverage"
   },
   "dependencies": {
-    "@pikku/core": "^0.7.8",
+    "@pikku/core": "^0.8.1",
     "path-to-regexp": "^8.2.0",
     "typescript": "^5.6"
   },

package/src/add-channel.ts

@@ -1,14 +1,18 @@
 import * as ts from 'typescript'
 import { getPropertyValue } from './get-property-value.js'
 import { pathToRegexp } from 'path-to-regexp'
-import { APIDocs } from '@pikku/core'
+import { APIDocs, PikkuEventTypes } from '@pikku/core'
 import {
   extractFunctionName,
   getPropertyAssignmentInitializer,
   matchesFilters,
 } from './utils.js'
 import type { ChannelMessageMeta, ChannelMeta } from '@pikku/core/channel'
-import type { InspectorFilters, InspectorState } from './types.js'
+import type {
+  InspectorFilters,
+  InspectorState,
+  InspectorLogger,
+} from './types.js'
 
 /**
  * Safely get the “initializer” expression of a property-like AST node:
@@ -363,7 +367,8 @@ export function addChannel(
   node: ts.Node,
   checker: ts.TypeChecker,
   state: InspectorState,
-  filters: InspectorFilters
+  filters: InspectorFilters,
+  logger: InspectorLogger
 ) {
   if (!ts.isCallExpression(node)) return
   const { expression, arguments: args } = node
@@ -391,7 +396,17 @@ export function addChannel(
   const tags = getPropertyValue(obj, 'tags') as string[] | undefined
   const query = getPropertyValue(obj, 'query') as string[] | []
 
-  if (!matchesFilters(filters, { tags }, { type: 'channel', name })) return
+  const filePath = node.getSourceFile().fileName
+
+  if (
+    !matchesFilters(
+      filters,
+      { tags },
+      { type: PikkuEventTypes.channel, name, filePath },
+      logger
+    )
+  )
+    return
 
   const connect = getPropertyAssignmentInitializer(
     obj,

package/src/add-functions.ts

@@ -1,5 +1,5 @@
 import * as ts from 'typescript'
-import { InspectorState, InspectorFilters } from './types.js'
+import { InspectorState, InspectorFilters, InspectorLogger } from './types.js'
 import { TypesMap } from './types-map.js'
 import {
   extractFunctionName,
@@ -231,7 +231,8 @@ export function addFunctions(
   node: ts.Node,
   checker: ts.TypeChecker,
   state: InspectorState,
-  filters: InspectorFilters
+  filters: InspectorFilters,
+  logger: InspectorLogger
 ) {
   if (!ts.isCallExpression(node)) return
 
@@ -305,10 +306,7 @@ export function addFunctions(
           services.services.push(original)
         }
       }
-    } else if (
-      ts.isIdentifier(firstParam.name) &&
-      !firstParam.name.text.startsWith('_')
-    ) {
+    } else if (ts.isIdentifier(firstParam.name)) {
       services.optimized = false
     }
   }

package/src/add-http-route.ts

@@ -2,13 +2,13 @@ import * as ts from 'typescript'
 import { getPropertyValue } from './get-property-value.js'
 import { pathToRegexp } from 'path-to-regexp'
 import { HTTPMethod } from '@pikku/core/http'
-import { APIDocs } from '@pikku/core'
+import { APIDocs, PikkuEventTypes } from '@pikku/core'
 import {
   extractFunctionName,
   getPropertyAssignmentInitializer,
   matchesFilters,
 } from './utils.js'
-import { InspectorState, InspectorFilters } from './types.js'
+import { InspectorState, InspectorFilters, InspectorLogger } from './types.js'
 
 /**
  * Populate metaInputTypes for a given route based on method, input type,
@@ -43,7 +43,8 @@ export const addHTTPRoute = (
   node: ts.Node,
   checker: ts.TypeChecker,
   state: InspectorState,
-  filters: InspectorFilters
+  filters: InspectorFilters,
+  logger: InspectorLogger
 ) => {
   // only look at calls
   if (!ts.isCallExpression(node)) return
@@ -69,7 +70,16 @@ export const addHTTPRoute = (
   const tags = (getPropertyValue(obj, 'tags') as string[]) || undefined
   const query = (getPropertyValue(obj, 'query') as string[]) || []
 
-  if (!matchesFilters(filters, { tags }, { type: 'http', name: route })) {
+  const filePath = node.getSourceFile().fileName
+
+  if (
+    !matchesFilters(
+      filters,
+      { tags },
+      { type: PikkuEventTypes.http, name: route, filePath },
+      logger
+    )
+  ) {
     return
   }
 

package/src/add-mcp-prompt.ts

@@ -0,0 +1,104 @@
+import * as ts from 'typescript'
+import { getPropertyValue } from './get-property-value.js'
+import { PikkuEventTypes } from '@pikku/core'
+import { InspectorFilters, InspectorState, InspectorLogger } from './types.js'
+import {
+  extractFunctionName,
+  getPropertyAssignmentInitializer,
+  matchesFilters,
+} from './utils.js'
+
+export const addMCPPrompt = (
+  node: ts.Node,
+  checker: ts.TypeChecker,
+  state: InspectorState,
+  filters: InspectorFilters,
+  logger: InspectorLogger
+) => {
+  if (!ts.isCallExpression(node)) {
+    return
+  }
+
+  const args = node.arguments
+  const firstArg = args[0]
+  const expression = node.expression
+
+  // Check if the call is to addMCPPrompt
+  if (!ts.isIdentifier(expression) || expression.text !== 'addMCPPrompt') {
+    return
+  }
+
+  if (!firstArg) {
+    return
+  }
+
+  if (ts.isObjectLiteralExpression(firstArg)) {
+    const obj = firstArg
+
+    const nameValue = getPropertyValue(obj, 'name') as string | null
+    const descriptionValue = getPropertyValue(obj, 'description') as
+      | string
+      | null
+    const tags = (getPropertyValue(obj, 'tags') as string[]) || undefined
+
+    const funcInitializer = getPropertyAssignmentInitializer(
+      obj,
+      'func',
+      true,
+      checker
+    )
+    if (!funcInitializer) {
+      console.error(`• No valid 'func' property for MCP prompt '${nameValue}'.`)
+      return
+    }
+
+    const pikkuFuncName = extractFunctionName(
+      funcInitializer,
+      checker
+    ).pikkuFuncName
+
+    if (!nameValue) {
+      console.error(`• MCP prompt is missing the required 'name' property.`)
+      return
+    }
+
+    if (!descriptionValue) {
+      console.error(`• MCP prompt '${nameValue}' is missing a description.`)
+      return
+    }
+
+    const filePath = node.getSourceFile().fileName
+
+    if (
+      !matchesFilters(
+        filters,
+        { tags },
+        { type: PikkuEventTypes.mcp, name: nameValue, filePath },
+        logger
+      )
+    ) {
+      return
+    }
+
+    // lookup existing function metadata
+    const fnMeta = state.functions.meta[pikkuFuncName]
+    if (!fnMeta) {
+      console.error(`• No function metadata found for '${pikkuFuncName}'.`)
+      return
+    }
+    const inputSchema = fnMeta.inputs?.[0] || null
+    const outputSchema = fnMeta.outputs?.[0] || null
+
+    state.mcpEndpoints.files.add(node.getSourceFile().fileName)
+
+    state.mcpEndpoints.promptsMeta[nameValue] = {
+      pikkuFuncName,
+      name: nameValue,
+      description: descriptionValue,
+      tags,
+      inputSchema,
+      outputSchema,
+      arguments: [], // Will be populated by CLI during serialization
+    }
+  }
+}

package/src/add-mcp-resource.ts

@@ -0,0 +1,116 @@
+import * as ts from 'typescript'
+import { getPropertyValue } from './get-property-value.js'
+import { PikkuEventTypes } from '@pikku/core'
+import { InspectorFilters, InspectorState, InspectorLogger } from './types.js'
+import {
+  extractFunctionName,
+  getPropertyAssignmentInitializer,
+  matchesFilters,
+} from './utils.js'
+
+export const addMCPResource = (
+  node: ts.Node,
+  checker: ts.TypeChecker,
+  state: InspectorState,
+  filters: InspectorFilters,
+  logger: InspectorLogger
+) => {
+  if (!ts.isCallExpression(node)) {
+    return
+  }
+
+  const args = node.arguments
+  const firstArg = args[0]
+  const expression = node.expression
+
+  // Check if the call is to addMCPResource
+  if (!ts.isIdentifier(expression) || expression.text !== 'addMCPResource') {
+    return
+  }
+
+  if (!firstArg) {
+    return
+  }
+
+  if (ts.isObjectLiteralExpression(firstArg)) {
+    const obj = firstArg
+
+    const uriValue = getPropertyValue(obj, 'uri') as string | null
+    const titleValue = getPropertyValue(obj, 'title') as string | null
+    const descriptionValue = getPropertyValue(obj, 'description') as
+      | string
+      | null
+    const streamingValue = getPropertyValue(obj, 'streaming') as boolean | null
+    const tags = (getPropertyValue(obj, 'tags') as string[]) || undefined
+
+    const funcInitializer = getPropertyAssignmentInitializer(
+      obj,
+      'func',
+      true,
+      checker
+    )
+    if (!funcInitializer) {
+      console.error(
+        `• No valid 'func' property for MCP resource '${uriValue}'.`
+      )
+      return
+    }
+
+    const pikkuFuncName = extractFunctionName(
+      funcInitializer,
+      checker
+    ).pikkuFuncName
+
+    if (!uriValue) {
+      console.error(`• MCP resource is missing the required 'uri' property.`)
+      return
+    }
+
+    if (!titleValue) {
+      console.error(
+        `• MCP resource '${uriValue}' is missing the required 'title' property.`
+      )
+      return
+    }
+
+    if (!descriptionValue) {
+      console.error(`• MCP resource '${uriValue}' is missing a description.`)
+      return
+    }
+
+    const filePath = node.getSourceFile().fileName
+
+    if (
+      !matchesFilters(
+        filters,
+        { tags },
+        { type: PikkuEventTypes.mcp, name: uriValue, filePath },
+        logger
+      )
+    ) {
+      return
+    }
+
+    // lookup existing function metadata
+    const fnMeta = state.functions.meta[pikkuFuncName]
+    if (!fnMeta) {
+      console.error(`• No function metadata found for '${pikkuFuncName}'.`)
+      return
+    }
+    const inputSchema = fnMeta.inputs?.[0] || null
+    const outputSchema = fnMeta.outputs?.[0] || null
+
+    state.mcpEndpoints.files.add(node.getSourceFile().fileName)
+
+    state.mcpEndpoints.resourcesMeta[uriValue] = {
+      pikkuFuncName,
+      uri: uriValue,
+      title: titleValue,
+      description: descriptionValue,
+      ...(streamingValue !== null && { streaming: streamingValue }),
+      tags,
+      inputSchema,
+      outputSchema,
+    }
+  }
+}

package/src/add-mcp-tool.ts

@@ -0,0 +1,107 @@
+import * as ts from 'typescript'
+import { getPropertyValue } from './get-property-value.js'
+import { PikkuEventTypes } from '@pikku/core'
+import { InspectorFilters, InspectorState, InspectorLogger } from './types.js'
+import {
+  extractFunctionName,
+  getPropertyAssignmentInitializer,
+  matchesFilters,
+} from './utils.js'
+
+export const addMCPTool = (
+  node: ts.Node,
+  checker: ts.TypeChecker,
+  state: InspectorState,
+  filters: InspectorFilters,
+  logger: InspectorLogger
+) => {
+  if (!ts.isCallExpression(node)) {
+    return
+  }
+
+  const args = node.arguments
+  const firstArg = args[0]
+  const expression = node.expression
+
+  // Check if the call is to addMCPTool
+  if (!ts.isIdentifier(expression) || expression.text !== 'addMCPTool') {
+    return
+  }
+
+  if (!firstArg) {
+    return
+  }
+
+  if (ts.isObjectLiteralExpression(firstArg)) {
+    const obj = firstArg
+
+    const nameValue = getPropertyValue(obj, 'name') as string | null
+    const titleValue = getPropertyValue(obj, 'title') as string | null
+    const descriptionValue = getPropertyValue(obj, 'description') as
+      | string
+      | null
+    const streamingValue = getPropertyValue(obj, 'streaming') as boolean | null
+    const tags = (getPropertyValue(obj, 'tags') as string[]) || undefined
+
+    const funcInitializer = getPropertyAssignmentInitializer(
+      obj,
+      'func',
+      true,
+      checker
+    )
+    if (!funcInitializer) {
+      console.error(`• No valid 'func' property for MCP tool '${nameValue}'.`)
+      return
+    }
+
+    const pikkuFuncName = extractFunctionName(
+      funcInitializer,
+      checker
+    ).pikkuFuncName
+
+    if (!nameValue) {
+      console.error(`• MCP tool is missing the required 'name' property.`)
+      return
+    }
+
+    if (!descriptionValue) {
+      console.error(`• MCP tool '${nameValue}' is missing a description.`)
+      return
+    }
+
+    const filePath = node.getSourceFile().fileName
+
+    if (
+      !matchesFilters(
+        filters,
+        { tags },
+        { type: PikkuEventTypes.mcp, name: nameValue, filePath },
+        logger
+      )
+    ) {
+      return
+    }
+
+    // lookup existing function metadata
+    const fnMeta = state.functions.meta[pikkuFuncName]
+    if (!fnMeta) {
+      console.error(`• No function metadata found for '${pikkuFuncName}'.`)
+      return
+    }
+    const inputSchema = fnMeta.inputs?.[0] || null
+    const outputSchema = fnMeta.outputs?.[0] || null
+
+    state.mcpEndpoints.files.add(node.getSourceFile().fileName)
+
+    state.mcpEndpoints.toolsMeta[nameValue] = {
+      pikkuFuncName,
+      name: nameValue,
+      title: titleValue || undefined,
+      description: descriptionValue,
+      ...(streamingValue !== null && { streaming: streamingValue }),
+      tags,
+      inputSchema,
+      outputSchema,
+    }
+  }
+}

package/src/add-queue-worker.ts

@@ -0,0 +1,92 @@
+import * as ts from 'typescript'
+import { getPropertyValue } from './get-property-value.js'
+import { APIDocs, PikkuEventTypes } from '@pikku/core'
+import { InspectorFilters, InspectorState, InspectorLogger } from './types.js'
+import {
+  extractFunctionName,
+  getPropertyAssignmentInitializer,
+  matchesFilters,
+} from './utils.js'
+
+export const addQueueWorker = (
+  node: ts.Node,
+  checker: ts.TypeChecker,
+  state: InspectorState,
+  filters: InspectorFilters,
+  logger: InspectorLogger
+) => {
+  if (!ts.isCallExpression(node)) {
+    return
+  }
+
+  const args = node.arguments
+  const firstArg = args[0]
+  const expression = node.expression
+
+  // Check if the call is to addQueueWorker
+  if (!ts.isIdentifier(expression) || expression.text !== 'addQueueWorker') {
+    return
+  }
+
+  if (!firstArg) {
+    return
+  }
+
+  if (ts.isObjectLiteralExpression(firstArg)) {
+    const obj = firstArg
+
+    const queueName = getPropertyValue(obj, 'queueName') as string | null
+    const docs = (getPropertyValue(obj, 'docs') as APIDocs) || undefined
+    const tags = (getPropertyValue(obj, 'tags') as string[]) || undefined
+
+    // --- find the referenced function ---
+    const funcInitializer = getPropertyAssignmentInitializer(
+      obj,
+      'func',
+      true,
+      checker
+    )
+    if (!funcInitializer) {
+      console.error(
+        `• No valid 'func' property for queue processor '${queueName}'.`
+      )
+      return
+    }
+
+    const pikkuFuncName = extractFunctionName(
+      funcInitializer,
+      checker
+    ).pikkuFuncName
+
+    if (!queueName) {
+      console.error(
+        `• No 'queueName' provided for queue processor function '${pikkuFuncName}'.`
+      )
+      return
+    }
+
+    const filePath = node.getSourceFile().fileName
+
+    if (
+      !matchesFilters(
+        filters,
+        { tags },
+        { type: PikkuEventTypes.queue, name: queueName, filePath },
+        logger
+      )
+    ) {
+      console.info(
+        `• Skipping queue processor '${pikkuFuncName}' for queue '${queueName}' due to filter mismatch.`
+      )
+      return
+    }
+
+    state.queueWorkers.files.add(node.getSourceFile().fileName)
+    state.queueWorkers.meta[queueName] = {
+      pikkuFuncName,
+      queueName,
+      docs,
+      tags,
+    }
+  }
+}

package/src/add-schedule.ts

@@ -1,14 +1,19 @@
 import * as ts from 'typescript'
 import { getPropertyValue } from './get-property-value.js'
-import { APIDocs } from '@pikku/core'
-import { InspectorFilters, InspectorState } from './types.js'
-import { extractFunctionName, matchesFilters } from './utils.js'
+import { APIDocs, PikkuEventTypes } from '@pikku/core'
+import { InspectorFilters, InspectorState, InspectorLogger } from './types.js'
+import {
+  extractFunctionName,
+  getPropertyAssignmentInitializer,
+  matchesFilters,
+} from './utils.js'
 
 export const addSchedule = (
   node: ts.Node,
   checker: ts.TypeChecker,
   state: InspectorState,
-  filters: InspectorFilters
+  filters: InspectorFilters,
+  logger: InspectorLogger
 ) => {
   if (!ts.isCallExpression(node)) {
     return
@@ -35,22 +40,21 @@ export const addSchedule = (
     const docs = (getPropertyValue(obj, 'docs') as APIDocs) || undefined
     const tags = (getPropertyValue(obj, 'tags') as string[]) || undefined
 
-    // --- find the referenced function ---
-    const funcProp = obj.properties.find(
-      (p) =>
-        ts.isPropertyAssignment(p) &&
-        ts.isIdentifier(p.name) &&
-        p.name.text === 'func'
-    ) as ts.PropertyAssignment | undefined
-
-    if (!funcProp || !ts.isIdentifier(funcProp.initializer)) {
+    const funcInitializer = getPropertyAssignmentInitializer(
+      obj,
+      'func',
+      true,
+      checker
+    )
+    if (!funcInitializer) {
       console.error(
         `• No valid 'func' property for scheduled task '${nameValue}'.`
       )
       return
     }
+
     const pikkuFuncName = extractFunctionName(
-      funcProp.initializer,
+      funcInitializer,
       checker
     ).pikkuFuncName
 
@@ -58,8 +62,15 @@ export const addSchedule = (
       return
     }
 
+    const filePath = node.getSourceFile().fileName
+
     if (
-      !matchesFilters(filters, { tags }, { type: 'schedule', name: nameValue })
+      !matchesFilters(
+        filters,
+        { tags },
+        { type: PikkuEventTypes.scheduler, name: nameValue, filePath },
+        logger
+      )
     ) {
       return
     }

package/src/inspector.ts

@@ -5,6 +5,7 @@ import {
   InspectorState,
   InspectorHTTPState,
   InspectorFilters,
+  InspectorLogger,
 } from './types.js'
 
 export const normalizeHTTPTypes = (
@@ -14,6 +15,7 @@ export const normalizeHTTPTypes = (
 }
 
 export const inspect = (
+  logger: InspectorLogger,
   routeFiles: string[],
   filters: InspectorFilters
 ): InspectorState => {
@@ -49,22 +51,32 @@ export const inspect = (
       meta: {},
       files: new Set(),
     },
+    queueWorkers: {
+      meta: {},
+      files: new Set(),
+    },
     rpc: {
       meta: {},
     },
+    mcpEndpoints: {
+      resourcesMeta: {},
+      toolsMeta: {},
+      promptsMeta: {},
+      files: new Set(),
+    },
   }
 
   // First sweep: add all functions
   for (const sourceFile of sourceFiles) {
     ts.forEachChild(sourceFile, (child) =>
-      visitSetup(checker, child, state, filters)
+      visitSetup(checker, child, state, filters, logger)
     )
   }
 
   // Second sweep: add all transports
   for (const sourceFile of sourceFiles) {
     ts.forEachChild(sourceFile, (child) =>
-      visitRoutes(checker, child, state, filters)
+      visitRoutes(checker, child, state, filters, logger)
     )
   }