@pikku/inspector 0.11.1 → 0.12.0

package/src/utils/extract-services.ts

@@ -1,5 +1,5 @@
 import * as ts from 'typescript'
-import { FunctionServicesMeta } from '@pikku/core'
+import { FunctionServicesMeta, FunctionWiresMeta } from '@pikku/core'
 
 /**
  * Extract services from a function's first parameter destructuring pattern
@@ -26,10 +26,43 @@ export function extractServicesFromFunction(
           services.services.push(original)
         }
       }
-    } else if (ts.isIdentifier(firstParam.name)) {
+    } else if (
+      ts.isIdentifier(firstParam.name) &&
+      !firstParam.name.text.startsWith('_')
+    ) {
       services.optimized = false
     }
   }
 
   return services
 }
+
+export function extractUsedWires(
+  handlerNode: ts.FunctionExpression | ts.ArrowFunction,
+  paramIndex: number
+): FunctionWiresMeta {
+  const param = handlerNode.parameters[paramIndex]
+  if (param && ts.isObjectBindingPattern(param.name)) {
+    const wires: string[] = []
+    for (const elem of param.name.elements) {
+      const propertyName =
+        elem.propertyName && ts.isIdentifier(elem.propertyName)
+          ? elem.propertyName.text
+          : ts.isIdentifier(elem.name)
+            ? elem.name.text
+            : undefined
+      if (propertyName) {
+        wires.push(propertyName)
+      }
+    }
+    return { optimized: true, wires }
+  }
+  if (
+    param &&
+    ts.isIdentifier(param.name) &&
+    !param.name.text.startsWith('_')
+  ) {
+    return { optimized: false, wires: [] }
+  }
+  return { optimized: true, wires: [] }
+}

package/src/utils/filter-inspector-state.test.ts

@@ -46,7 +46,7 @@ function createMockInspectorState(): Omit<InspectorState, 'typesLookup'> {
       meta: {
         get: {
           '/api/users': {
-            pikkuFuncName: 'getUsers',
+            pikkuFuncId: 'getUsers',
             route: '/api/users',
             method: 'GET',
             tags: ['api', 'public'],
@@ -54,7 +54,7 @@ function createMockInspectorState(): Omit<InspectorState, 'typesLookup'> {
             permissions: [],
           },
           '/admin/settings': {
-            pikkuFuncName: 'getAdminSettings',
+            pikkuFuncId: 'getAdminSettings',
             route: '/admin/settings',
             method: 'GET',
             tags: ['admin'],
@@ -64,7 +64,7 @@ function createMockInspectorState(): Omit<InspectorState, 'typesLookup'> {
         },
         post: {
           '/api/users': {
-            pikkuFuncName: 'createUser',
+            pikkuFuncId: 'createUser',
             route: '/api/users',
             method: 'POST',
             tags: ['api'],
@@ -152,13 +152,13 @@ function createMockInspectorState(): Omit<InspectorState, 'typesLookup'> {
     channels: {
       meta: {
         'chat-channel': {
-          pikkuFuncName: 'handleChatMessage',
+          pikkuFuncId: 'handleChatMessage',
           tags: ['realtime', 'public'],
           middleware: [],
           permissions: [],
         },
         'admin-channel': {
-          pikkuFuncName: 'handleAdminMessage',
+          pikkuFuncId: 'handleAdminMessage',
           tags: ['realtime', 'admin'],
           middleware: [{ type: 'wire', name: 'authMiddleware' }],
           permissions: [],
@@ -169,13 +169,13 @@ function createMockInspectorState(): Omit<InspectorState, 'typesLookup'> {
     scheduledTasks: {
       meta: {
         'daily-report': {
-          pikkuFuncName: 'dailyReport',
+          pikkuFuncId: 'dailyReport',
           schedule: '0 0 * * *',
           tags: ['cron', 'reports'],
           middleware: [],
         },
         'hourly-cleanup': {
-          pikkuFuncName: 'hourlyCleanup',
+          pikkuFuncId: 'hourlyCleanup',
           schedule: '0 * * * *',
           tags: ['cron', 'maintenance'],
           middleware: [],
@@ -186,20 +186,27 @@ function createMockInspectorState(): Omit<InspectorState, 'typesLookup'> {
     queueWorkers: {
       meta: {
         'email-worker': {
-          pikkuFuncName: 'sendEmailWorker',
-          queueName: 'email-queue',
+          pikkuFuncId: 'sendEmailWorker',
+          name: 'email-queue',
           tags: ['queue', 'email'],
           middleware: [],
         },
         'notification-worker': {
-          pikkuFuncName: 'sendNotificationWorker',
-          queueName: 'notification-queue',
+          pikkuFuncId: 'sendNotificationWorker',
+          name: 'notification-queue',
           tags: ['queue', 'notifications'],
           middleware: [],
         },
       },
       files: new Set(['/test/project/src/workers/email.ts']),
     },
+    workflows: {
+      meta: {},
+      files: new Map(),
+      graphMeta: {},
+      graphFiles: new Map(),
+      invokedWorkflows: new Set(),
+    },
     rpc: {
       internalMeta: {},
       internalFiles: new Map(),
@@ -212,7 +219,7 @@ function createMockInspectorState(): Omit<InspectorState, 'typesLookup'> {
         'search-tool': {
           name: 'search-tool',
           description: 'Search tool',
-          pikkuFuncName: 'mcpSearchTool',
+          pikkuFuncId: 'mcpSearchTool',
           tags: ['mcp', 'search'],
           middleware: [],
           permissions: [],
@@ -220,7 +227,7 @@ function createMockInspectorState(): Omit<InspectorState, 'typesLookup'> {
         'analyze-tool': {
           name: 'analyze-tool',
           description: 'Analyze tool',
-          pikkuFuncName: 'mcpAnalyzeTool',
+          pikkuFuncId: 'mcpAnalyzeTool',
           tags: ['mcp', 'analytics'],
           middleware: [],
           permissions: [],
@@ -231,7 +238,7 @@ function createMockInspectorState(): Omit<InspectorState, 'typesLookup'> {
           title: 'Docs Resource',
           description: 'Documentation resource',
           uri: 'docs://resource',
-          pikkuFuncName: 'mcpDocsResource',
+          pikkuFuncId: 'mcpDocsResource',
           tags: ['mcp', 'docs'],
           middleware: [],
           permissions: [],
@@ -241,7 +248,7 @@ function createMockInspectorState(): Omit<InspectorState, 'typesLookup'> {
         'help-prompt': {
           name: 'help-prompt',
           description: 'Help prompt',
-          pikkuFuncName: 'mcpHelpPrompt',
+          pikkuFuncId: 'mcpHelpPrompt',
           tags: ['mcp', 'help'],
           middleware: [],
           permissions: [],
@@ -255,14 +262,14 @@ function createMockInspectorState(): Omit<InspectorState, 'typesLookup'> {
           'my-cli': {
             commands: {
               build: {
-                pikkuFuncName: 'cliCommand',
+                pikkuFuncId: 'cliCommand',
                 tags: ['cli', 'build'],
                 middleware: [],
                 positionals: [],
                 options: {},
               } as any,
               test: {
-                pikkuFuncName: 'cliTestCommand',
+                pikkuFuncId: 'cliTestCommand',
                 tags: ['cli', 'test'],
                 middleware: [],
                 positionals: [],
@@ -275,11 +282,18 @@ function createMockInspectorState(): Omit<InspectorState, 'typesLookup'> {
       files: new Set(['/test/project/src/cli/commands.ts']),
     },
     middleware: {
-      meta: {},
+      definitions: {},
+      instances: {},
+      tagMiddleware: new Map(),
+    },
+    channelMiddleware: {
+      definitions: {},
+      instances: {},
       tagMiddleware: new Map(),
     },
     permissions: {
-      meta: {},
+      definitions: {},
+      instances: {},
       tagPermissions: new Map(),
     },
     serviceAggregation: {
@@ -413,7 +427,7 @@ describe('filterInspectorState', () => {
 
       assert.equal(Object.keys(result.http.meta.get).length, 1)
       assert.ok(result.http.meta.get['/api/users'])
-      assert.equal(result.http.meta.get['/api/users'].pikkuFuncName, 'getUsers')
+      assert.equal(result.http.meta.get['/api/users'].pikkuFuncId, 'getUsers')
     })
 
     test('should filter HTTP routes by name wildcard', () => {

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

@@ -1,7 +1,10 @@
 import { InspectorState, InspectorFilters, InspectorLogger } from '../types.js'
-import { PikkuWiringTypes } from '@pikku/core'
+import { PikkuWiringTypes, parseVersionedId } from '@pikku/core'
 import { aggregateRequiredServices } from './post-process.js'
 
+// Module-level Set to track warned groups across multiple filter calls
+const globalWarnedGroups = new Set<string>()
+
 /**
  * Match a value against a pattern with wildcard support
  * Supports "*" at the beginning, end, or both (e.g., "send*", "*Payment", "*process*")
@@ -39,8 +42,10 @@ function matchesFilters(
     filePath?: string
     httpRoute?: string
     httpMethod?: string
+    groupBasePath?: string
   },
-  logger: InspectorLogger
+  logger: InspectorLogger,
+  warnedGroups?: Set<string>
 ): boolean {
   // If no filters, allow everything
   if (Object.keys(filters).length === 0) return true
@@ -87,10 +92,13 @@ function matchesFilters(
     }
   }
 
-  // Check name filter
+  // Check name filter (match against both full ID and base name for versioned functions)
   if (filters.names && filters.names.length > 0) {
-    const nameMatches = filters.names.some((pattern) =>
-      matchesWildcard(meta.name, pattern)
+    const { baseName } = parseVersionedId(meta.name)
+    const nameMatches = filters.names.some(
+      (pattern) =>
+        matchesWildcard(meta.name, pattern) ||
+        (baseName !== meta.name && matchesWildcard(baseName, pattern))
     )
     if (!nameMatches) {
       logger.debug(`⒡ Filtered by name: ${meta.type}:${meta.name}`)
@@ -107,6 +115,23 @@ function matchesFilters(
       logger.debug(`⒡ Filtered by HTTP route: ${meta.httpRoute}`)
       return false
     }
+
+    // If route is part of a wireHTTPRoutes group, check if filter is at group level
+    if (meta.groupBasePath && warnedGroups) {
+      const groupMatches = filters.httpRoutes.some(
+        (pattern) =>
+          matchesWildcard(meta.groupBasePath!, pattern) ||
+          matchesWildcard(meta.groupBasePath! + '/*', pattern)
+      )
+      if (!groupMatches && !warnedGroups.has(meta.groupBasePath)) {
+        warnedGroups.add(meta.groupBasePath)
+        logger.warn(
+          `Filtering within wireHTTPRoutes group is not yet supported. ` +
+            `Route '${meta.httpRoute}' is part of group '${meta.groupBasePath}'. ` +
+            `Use '--httpRoutes=${meta.groupBasePath}/*' to filter the entire group.`
+        )
+      }
+    }
   }
 
   // Check HTTP method filter
@@ -181,6 +206,11 @@ export function filterInspectorState(
       meta: JSON.parse(JSON.stringify(state.channels.meta)),
       files: new Set<string>(), // Will be repopulated with filtered files
     },
+    triggers: {
+      ...state.triggers,
+      meta: JSON.parse(JSON.stringify(state.triggers?.meta ?? {})),
+      files: new Set<string>(),
+    },
     scheduledTasks: {
       ...state.scheduledTasks,
       meta: JSON.parse(JSON.stringify(state.scheduledTasks.meta)),
@@ -198,7 +228,12 @@ export function filterInspectorState(
         JSON.stringify(state.mcpEndpoints.resourcesMeta)
       ),
       promptsMeta: JSON.parse(JSON.stringify(state.mcpEndpoints.promptsMeta)),
-      files: new Set<string>(), // Will be repopulated with filtered files
+      files: new Set<string>(),
+    },
+    agents: {
+      ...state.agents,
+      agentsMeta: JSON.parse(JSON.stringify(state.agents?.agentsMeta ?? {})),
+      files: new Map(),
     },
     cli: {
       ...state.cli,
@@ -214,31 +249,31 @@ export function filterInspectorState(
       const routeMeta = routes[route]
 
       // Get function file path for directory filtering
-      const funcFile = filteredState.functions.files.get(
-        routeMeta.pikkuFuncName
-      )
+      const funcFile = filteredState.functions.files.get(routeMeta.pikkuFuncId)
       const filePath = funcFile?.path
 
       const matches = matchesFilters(
         filters,
         {
           type: 'http' as PikkuWiringTypes,
-          name: routeMeta.pikkuFuncName, // Use function name, not route
+          name: routeMeta.pikkuFuncId, // Use function name, not route
           tags: routeMeta.tags,
           filePath,
           httpRoute: routeMeta.route,
           httpMethod: routeMeta.method,
+          groupBasePath: routeMeta.groupBasePath,
         },
-        logger
+        logger,
+        globalWarnedGroups
       )
 
       if (!matches) {
         delete routes[route]
       } else {
         // Track used functions/middleware/permissions
-        if (routeMeta.pikkuFuncName) {
+        if (routeMeta.pikkuFuncId) {
           filteredState.serviceAggregation.usedFunctions.add(
-            routeMeta.pikkuFuncName
+            routeMeta.pikkuFuncId
           )
         }
         extractWireNames(routeMeta.middleware).forEach((name: string) =>
@@ -275,9 +310,9 @@ export function filterInspectorState(
     if (!matches) {
       delete filteredState.channels.meta[name]
     } else {
-      if (channelMeta.pikkuFuncName) {
+      if (channelMeta.pikkuFuncId) {
         filteredState.serviceAggregation.usedFunctions.add(
-          channelMeta.pikkuFuncName
+          channelMeta.pikkuFuncId
         )
       }
       extractWireNames(channelMeta.middleware).forEach((name: string) =>
@@ -294,6 +329,35 @@ export function filterInspectorState(
     filteredState.channels.files = new Set(state.channels.files)
   }
 
+  // Filter triggers
+  for (const name of Object.keys(filteredState.triggers.meta)) {
+    const triggerMeta = filteredState.triggers.meta[name]
+    const matches = matchesFilters(
+      filters,
+      {
+        type: 'trigger' as PikkuWiringTypes,
+        name,
+        tags: triggerMeta.tags,
+      },
+      logger
+    )
+
+    if (!matches) {
+      delete filteredState.triggers.meta[name]
+    } else {
+      if (triggerMeta.pikkuFuncId) {
+        filteredState.serviceAggregation.usedFunctions.add(
+          triggerMeta.pikkuFuncId
+        )
+      }
+    }
+  }
+
+  // Repopulate triggers.files if any triggers remain
+  if (Object.keys(filteredState.triggers.meta).length > 0) {
+    filteredState.triggers.files = new Set(state.triggers.files)
+  }
+
   // Filter scheduled tasks
   for (const name of Object.keys(filteredState.scheduledTasks.meta)) {
     const taskMeta = filteredState.scheduledTasks.meta[name]
@@ -310,10 +374,8 @@ export function filterInspectorState(
     if (!matches) {
       delete filteredState.scheduledTasks.meta[name]
     } else {
-      if (taskMeta.pikkuFuncName) {
-        filteredState.serviceAggregation.usedFunctions.add(
-          taskMeta.pikkuFuncName
-        )
+      if (taskMeta.pikkuFuncId) {
+        filteredState.serviceAggregation.usedFunctions.add(taskMeta.pikkuFuncId)
       }
       extractWireNames(taskMeta.middleware).forEach((name: string) =>
         filteredState.serviceAggregation.usedMiddleware.add(name)
@@ -342,9 +404,9 @@ export function filterInspectorState(
     if (!matches) {
       delete filteredState.queueWorkers.meta[name]
     } else {
-      if (workerMeta.pikkuFuncName) {
+      if (workerMeta.pikkuFuncId) {
         filteredState.serviceAggregation.usedFunctions.add(
-          workerMeta.pikkuFuncName
+          workerMeta.pikkuFuncId
         )
       }
       extractWireNames(workerMeta.middleware).forEach((name: string) =>
@@ -374,10 +436,8 @@ export function filterInspectorState(
     if (!matches) {
       delete filteredState.mcpEndpoints.toolsMeta[name]
     } else {
-      if (toolMeta.pikkuFuncName) {
-        filteredState.serviceAggregation.usedFunctions.add(
-          toolMeta.pikkuFuncName
-        )
+      if (toolMeta.pikkuFuncId) {
+        filteredState.serviceAggregation.usedFunctions.add(toolMeta.pikkuFuncId)
       }
       extractWireNames(toolMeta.middleware).forEach((name: string) =>
         filteredState.serviceAggregation.usedMiddleware.add(name)
@@ -404,9 +464,9 @@ export function filterInspectorState(
     if (!matches) {
       delete filteredState.mcpEndpoints.resourcesMeta[name]
     } else {
-      if (resourceMeta.pikkuFuncName) {
+      if (resourceMeta.pikkuFuncId) {
         filteredState.serviceAggregation.usedFunctions.add(
-          resourceMeta.pikkuFuncName
+          resourceMeta.pikkuFuncId
         )
       }
       extractWireNames(resourceMeta.middleware).forEach((name: string) =>
@@ -434,9 +494,9 @@ export function filterInspectorState(
     if (!matches) {
       delete filteredState.mcpEndpoints.promptsMeta[name]
     } else {
-      if (promptMeta.pikkuFuncName) {
+      if (promptMeta.pikkuFuncId) {
         filteredState.serviceAggregation.usedFunctions.add(
-          promptMeta.pikkuFuncName
+          promptMeta.pikkuFuncId
         )
       }
       extractWireNames(promptMeta.middleware).forEach((name: string) =>
@@ -457,6 +517,40 @@ export function filterInspectorState(
     filteredState.mcpEndpoints.files = new Set(state.mcpEndpoints.files)
   }
 
+  // Filter AI agents
+  for (const name of Object.keys(filteredState.agents.agentsMeta)) {
+    const agentMeta = filteredState.agents.agentsMeta[name]
+    const matches = matchesFilters(
+      filters,
+      {
+        type: 'agent' as PikkuWiringTypes,
+        name,
+        tags: agentMeta.tags,
+      },
+      logger
+    )
+
+    if (!matches) {
+      delete filteredState.agents.agentsMeta[name]
+    } else {
+      if (agentMeta.pikkuFuncId) {
+        filteredState.serviceAggregation.usedFunctions.add(
+          agentMeta.pikkuFuncId
+        )
+      }
+      extractWireNames(agentMeta.middleware).forEach((name: string) =>
+        filteredState.serviceAggregation.usedMiddleware.add(name)
+      )
+      extractWireNames(agentMeta.permissions).forEach((name: string) =>
+        filteredState.serviceAggregation.usedPermissions.add(name)
+      )
+    }
+  }
+
+  if (Object.keys(filteredState.agents.agentsMeta).length > 0) {
+    filteredState.agents.files = new Map(state.agents.files)
+  }
+
   // Filter CLI programs (note: CLI filtering might be more complex with nested commands)
   const referencedRenderers = new Set<string>()
 
@@ -479,9 +573,9 @@ export function filterInspectorState(
       if (!matches) {
         delete programMeta.commands[commandName]
       } else {
-        if (commandMeta.pikkuFuncName) {
+        if (commandMeta.pikkuFuncId) {
           filteredState.serviceAggregation.usedFunctions.add(
-            commandMeta.pikkuFuncName
+            commandMeta.pikkuFuncId
           )
         }
         extractWireNames(commandMeta.middleware).forEach((name: string) =>
@@ -517,6 +611,21 @@ export function filterInspectorState(
     filteredState.cli.files = new Set(state.cli.files)
   }
 
+  // Post-filter version expansion: include all versions of matched functions
+  const includedBaseNames = new Set<string>()
+  for (const funcId of filteredState.serviceAggregation.usedFunctions) {
+    const { baseName } = parseVersionedId(funcId)
+    includedBaseNames.add(baseName)
+  }
+  if (includedBaseNames.size > 0) {
+    for (const funcId of Object.keys(state.functions.meta)) {
+      const { baseName } = parseVersionedId(funcId)
+      if (includedBaseNames.has(baseName)) {
+        filteredState.serviceAggregation.usedFunctions.add(funcId)
+      }
+    }
+  }
+
   // Recalculate requiredServices based on filtered functions/middleware/permissions
   // Need to cast to InspectorState temporarily for aggregateRequiredServices
   const stateForAggregation = filteredState as InspectorState

package/src/utils/get-property-value.ts

@@ -1,10 +1,36 @@
 import * as ts from 'typescript'
 import { ErrorCode } from '../error-codes.js'
 
+/**
+ * Extracts an array of strings from an object property.
+ */
+export const getArrayPropertyValue = (
+  obj: ts.ObjectLiteralExpression,
+  propertyName: string
+): string[] | null => {
+  const property = obj.properties.find(
+    (p) =>
+      ts.isPropertyAssignment(p) &&
+      ts.isIdentifier(p.name) &&
+      p.name.text === propertyName
+  )
+
+  if (property && ts.isPropertyAssignment(property)) {
+    const initializer = property.initializer
+    if (ts.isArrayLiteralExpression(initializer)) {
+      return initializer.elements
+        .filter(ts.isStringLiteral)
+        .map((element) => element.text)
+    }
+  }
+
+  return null
+}
+
 export const getPropertyValue = (
   obj: ts.ObjectLiteralExpression,
   propertyName: string
-): string | string[] | null | boolean => {
+): string | string[] | number | null | boolean => {
   const property = obj.properties.find(
     (p) =>
       ts.isPropertyAssignment(p) &&
@@ -41,7 +67,13 @@ export const getPropertyValue = (
       return false
     }
 
-    // Handle string literals for other properties
+    if (ts.isNumericLiteral(initializer)) {
+      if (propertyName === 'name' || propertyName === 'schedule') {
+        return initializer.text
+      }
+      return Number(initializer.text)
+    }
+
     if (
       ts.isStringLiteral(initializer) ||
       ts.isNoSubstitutionTemplateLiteral(initializer)
@@ -49,7 +81,6 @@ export const getPropertyValue = (
       return initializer.text
     }
 
-    // Handle other initializer types if necessary
     return initializer.getText()
   }
 
@@ -57,7 +88,7 @@ export const getPropertyValue = (
 }
 
 /**
- * Extracts common wire metadata (tags, summary, description, errors) directly from an object
+ * Extracts common wire metadata (title, tags, summary, description, errors) directly from an object
  * @param obj - The TypeScript object literal expression to extract metadata from
  * @param wiringType - The type of wiring (e.g., 'HTTP route', 'Channel', 'Queue worker')
  * @param wiringName - The name/identifier of the wiring (e.g., route path, channel name)
@@ -70,12 +101,16 @@ export const getCommonWireMetaData = (
   wiringName: string | null,
   logger?: { critical: (code: ErrorCode, message: string) => void }
 ): {
+  disabled?: true
+  title?: string
   tags?: string[]
   summary?: string
   description?: string
   errors?: string[]
 } => {
   const metadata: {
+    disabled?: true
+    title?: string
     tags?: string[]
     summary?: string
     description?: string
@@ -86,7 +121,17 @@ export const getCommonWireMetaData = (
     if (ts.isPropertyAssignment(prop) && ts.isIdentifier(prop.name)) {
       const propName = prop.name.text
 
-      if (propName === 'summary' && ts.isStringLiteral(prop.initializer)) {
+      if (
+        propName === 'disabled' &&
+        prop.initializer.kind === ts.SyntaxKind.TrueKeyword
+      ) {
+        metadata.disabled = true
+      } else if (propName === 'title' && ts.isStringLiteral(prop.initializer)) {
+        metadata.title = prop.initializer.text
+      } else if (
+        propName === 'summary' &&
+        ts.isStringLiteral(prop.initializer)
+      ) {
         metadata.summary = prop.initializer.text
       } else if (
         propName === 'description' &&

package/src/utils/hash.ts

@@ -0,0 +1,26 @@
+import { createHash } from 'crypto'
+
+export function canonicalJSON(obj: unknown): string {
+  return JSON.stringify(sortDeep(obj))
+}
+
+function sortDeep(value: unknown): unknown {
+  if (value === null || value === undefined) {
+    return value
+  }
+  if (Array.isArray(value)) {
+    return value.map(sortDeep)
+  }
+  if (typeof value === 'object') {
+    const sorted: Record<string, unknown> = {}
+    for (const key of Object.keys(value as Record<string, unknown>).sort()) {
+      sorted[key] = sortDeep((value as Record<string, unknown>)[key])
+    }
+    return sorted
+  }
+  return value
+}
+
+export function hashString(input: string, length: number = 16): string {
+  return createHash('sha256').update(input).digest('hex').slice(0, length)
+}