@pikku/inspector 0.11.1 → 0.12.0

package/src/utils/permissions.ts

@@ -4,8 +4,8 @@ import { extractFunctionName } from './extract-function-name.js'
 import { InspectorState } from '../types.js'
 
 /**
- * Extract permission pikkuFuncNames from an expression (array or object literal)
- * Resolves each identifier to its pikkuFuncName using extractFunctionName
+ * Extract permission pikkuFuncIds from an expression (array or object literal)
+ * Resolves each identifier to its pikkuFuncId using extractFunctionName
  * Also handles call expressions (like rolePermission({...}))
  *
  * Supports both formats:
@@ -22,17 +22,17 @@ export function extractPermissionPikkuNames(
   // Helper to extract from a single element
   const extractFromElement = (element: ts.Expression) => {
     if (ts.isIdentifier(element)) {
-      const { pikkuFuncName } = extractFunctionName(element, checker, rootDir)
-      names.push(pikkuFuncName)
+      const { pikkuFuncId } = extractFunctionName(element, checker, rootDir)
+      names.push(pikkuFuncId)
     } else if (ts.isCallExpression(element)) {
       // Handle call expressions like hasEmailQuota(100) or rolePermission({...})
       // Extract the function being called (e.g., 'hasEmailQuota' from 'hasEmailQuota(100)')
-      const { pikkuFuncName } = extractFunctionName(
+      const { pikkuFuncId } = extractFunctionName(
         element.expression,
         checker,
         rootDir
       )
-      names.push(pikkuFuncName)
+      names.push(pikkuFuncId)
     } else if (ts.isArrayLiteralExpression(element)) {
       // Nested array (for Record values that are arrays)
       for (const nestedElement of element.elements) {
@@ -141,11 +141,11 @@ export function resolveHTTPPermissions(
       state.rootDir
     )
     for (const name of permissionNames) {
-      const meta = state.permissions.meta[name]
+      const def = state.permissions.definitions[name]
       resolved.push({
         type: 'wire',
         name,
-        inline: meta?.exportedName === null,
+        inline: def?.exportedName === null,
       })
     }
   }
@@ -187,11 +187,11 @@ function resolveTagAndExplicitPermissions(
       state.rootDir
     )
     for (const name of permissionNames) {
-      const meta = state.permissions.meta[name]
+      const def = state.permissions.definitions[name]
       resolved.push({
         type: 'wire',
         name,
-        inline: meta?.exportedName === null,
+        inline: def?.exportedName === null,
       })
     }
   }

package/src/utils/post-process.ts

@@ -1,15 +1,19 @@
-import * as ts from 'typescript'
-import { InspectorState } from '../types.js'
+import {
+  InspectorState,
+  InspectorLogger,
+  InspectorOptions,
+  InspectorModelConfig,
+  ExternalPackageConfig,
+  MiddlewareGroupMeta,
+  InspectorDiagnostic,
+} from '../types.js'
 import {
   FunctionServicesMeta,
   MiddlewareMetadata,
   PermissionMetadata,
 } from '@pikku/core'
 import { extractTypeKeys } from './type-utils.js'
-import {
-  extractAllServiceMetadata,
-  ServiceMetadata,
-} from './extract-service-metadata.js'
+import { ErrorCode } from '../error-codes.js'
 
 /**
  * Helper to extract wire-level middleware/permission names from metadata.
@@ -133,7 +137,7 @@ export function aggregateRequiredServices(
 
   // 2. Services from used middleware (individual + groups)
   usedMiddleware.forEach((middlewareName) => {
-    const middlewareMeta = state.middleware.meta[middlewareName]
+    const middlewareMeta = state.middleware.definitions[middlewareName]
     if (middlewareMeta?.services) {
       addServices(middlewareMeta.services)
     }
@@ -141,7 +145,7 @@ export function aggregateRequiredServices(
 
   // 3. Services from used permissions (individual + groups)
   usedPermissions.forEach((permissionName) => {
-    const permissionMeta = state.permissions.meta[permissionName]
+    const permissionMeta = state.permissions.definitions[permissionName]
     if (permissionMeta?.services) {
       addServices(permissionMeta.services)
     }
@@ -220,50 +224,286 @@ export function aggregateRequiredServices(
   }
 }
 
-/**
- * Extract service interface metadata for all user-defined services.
- * This extracts metadata for services in SingletonServices and Services types
- * to generate documentation for AI consumption.
- *
- * Must be called after aggregateRequiredServices() to ensure types are loaded.
- */
-export function extractServiceInterfaceMetadata(
+export function validateSecretOverrides(
+  logger: InspectorLogger,
   state: InspectorState | Omit<InspectorState, 'typesLookup'>,
-  checker: ts.TypeChecker
+  externalPackages?: Record<string, ExternalPackageConfig>
 ): void {
-  if (!('typesLookup' in state)) {
-    return
+  if (!externalPackages) return
+
+  const secretNames = new Set(state.secrets.definitions.map((d) => d.name))
+
+  for (const [namespace, pkgConfig] of Object.entries(externalPackages)) {
+    if (!pkgConfig.secretOverrides) continue
+
+    for (const secretKey of Object.keys(pkgConfig.secretOverrides)) {
+      if (!secretNames.has(secretKey)) {
+        const availableSecrets = Array.from(secretNames)
+        logger.critical(
+          ErrorCode.INVALID_VALUE,
+          `Secret override '${secretKey}' in external package '${namespace}' (${pkgConfig.package}) does not exist. Available secrets: ${availableSecrets.join(', ') || 'none'}`
+        )
+      }
+    }
   }
+}
 
-  const allMetadata: ServiceMetadata[] = []
+export function computeResolvedIOTypes(state: InspectorState): void {
+  const { functions } = state
+  for (const [pikkuFuncId, meta] of Object.entries(functions.meta)) {
+    const input = meta.inputs?.[0]
+    const output = meta.outputs?.[0]
 
-  const singletonServicesTypes = state.typesLookup.get('SingletonServices')
-  if (singletonServicesTypes && singletonServicesTypes.length > 0) {
-    const singletonMeta = extractAllServiceMetadata(
-      singletonServicesTypes[0],
-      checker,
-      state.rootDir
-    )
-    allMetadata.push(...singletonMeta)
+    let inputType = 'null'
+    if (input) {
+      try {
+        inputType = functions.typesMap.getTypeMeta(input).uniqueName
+      } catch {
+        inputType = input
+      }
+    }
+
+    let outputType = 'null'
+    if (output) {
+      try {
+        outputType = functions.typesMap.getTypeMeta(output).uniqueName
+      } catch {
+        outputType = output
+      }
+    }
+
+    state.resolvedIOTypes[pikkuFuncId] = { inputType, outputType }
   }
+}
 
-  const servicesTypes = state.typesLookup.get('Services')
-  if (servicesTypes && servicesTypes.length > 0) {
-    const wireServicesMeta = extractAllServiceMetadata(
-      servicesTypes[0],
-      checker,
-      state.rootDir
-    )
+const serializeGroupMap = (
+  groupMap: Map<string, MiddlewareGroupMeta>
+): Record<string, MiddlewareGroupMeta> => {
+  const result: Record<string, MiddlewareGroupMeta> = {}
+  for (const [key, meta] of groupMap.entries()) {
+    result[key] = {
+      exportName: meta.exportName,
+      sourceFile: meta.sourceFile,
+      position: meta.position,
+      services: meta.services,
+      count: meta.count,
+      instanceIds: meta.instanceIds,
+      isFactory: meta.isFactory,
+    }
+  }
+  return result
+}
 
-    const singletonNames = new Set(
-      state.serviceAggregation.allSingletonServices
-    )
-    const uniqueWireServices = wireServicesMeta.filter(
-      (meta) => !singletonNames.has(meta.name)
-    )
+export function computeMiddlewareGroupsMeta(state: InspectorState): void {
+  state.middlewareGroupsMeta = {
+    definitions: state.middleware.definitions,
+    instances: state.middleware.instances,
+    httpGroups: serializeGroupMap(state.http.routeMiddleware),
+    tagGroups: serializeGroupMap(state.middleware.tagMiddleware),
+    channelMiddleware: {
+      definitions: state.channelMiddleware.definitions,
+      instances: state.channelMiddleware.instances,
+      tagGroups: serializeGroupMap(state.channelMiddleware.tagMiddleware),
+    },
+  }
+}
+
+export function computePermissionsGroupsMeta(state: InspectorState): void {
+  const httpGroups: Record<string, any> = {}
+  for (const [pattern, meta] of state.http.routePermissions.entries()) {
+    httpGroups[pattern] = {
+      exportName: meta.exportName,
+      sourceFile: meta.sourceFile,
+      position: meta.position,
+      services: meta.services,
+      count: meta.count,
+      instanceIds: meta.instanceIds,
+      isFactory: meta.isFactory,
+    }
+  }
+
+  const tagGroups: Record<string, any> = {}
+  for (const [tag, meta] of state.permissions.tagPermissions.entries()) {
+    tagGroups[tag] = {
+      exportName: meta.exportName,
+      sourceFile: meta.sourceFile,
+      position: meta.position,
+      services: meta.services,
+      count: meta.count,
+      instanceIds: meta.instanceIds,
+      isFactory: meta.isFactory,
+    }
+  }
 
-    allMetadata.push(...uniqueWireServices)
+  state.permissionsGroupsMeta = {
+    definitions: state.permissions.definitions,
+    httpGroups,
+    tagGroups,
+  }
+}
+
+const PRIMITIVE_TYPES = new Set([
+  'boolean',
+  'string',
+  'number',
+  'null',
+  'undefined',
+  'void',
+  'any',
+  'unknown',
+  'never',
+])
+
+export function computeRequiredSchemas(
+  state: InspectorState,
+  options: InspectorOptions
+): void {
+  const { functions, schemaLookup } = state
+  const schemasFromTypes = options.schemaConfig?.schemasFromTypes
+
+  state.requiredSchemas = new Set<string>([
+    ...Object.values(functions.meta)
+      .map(({ inputs, outputs }) => {
+        const types: (string | undefined)[] = []
+        if (inputs?.[0]) {
+          try {
+            types.push(functions.typesMap.getUniqueName(inputs[0]))
+          } catch {
+            types.push(inputs[0])
+          }
+        }
+        if (outputs?.[0]) {
+          try {
+            types.push(functions.typesMap.getUniqueName(outputs[0]))
+          } catch {
+            types.push(outputs[0])
+          }
+        }
+        return types
+      })
+      .flat()
+      .filter((s): s is string => !!s && !PRIMITIVE_TYPES.has(s)),
+    ...functions.typesMap.customTypes.keys(),
+    ...(schemasFromTypes || []),
+    ...Array.from(schemaLookup.keys()),
+  ])
+}
+
+export function validateAgentModels(
+  logger: InspectorLogger,
+  state: InspectorState | Omit<InspectorState, 'typesLookup'>,
+  modelConfig?: InspectorModelConfig
+): void {
+  const aliases = modelConfig?.models ?? {}
+
+  for (const [, meta] of Object.entries(state.agents.agentsMeta)) {
+    const model = meta.model
+    if (!model) {
+      logger.critical(
+        ErrorCode.MISSING_MODEL,
+        `AI agent '${meta.name}' is missing the 'model' property.`
+      )
+      continue
+    }
+    if (model.includes('/')) continue
+    if (!aliases[model]) {
+      const available = Object.keys(aliases)
+      logger.critical(
+        ErrorCode.INVALID_MODEL,
+        `AI agent '${meta.name}' uses model alias '${model}' which is not defined in pikku.config.json models. ` +
+          `Available aliases: ${available.join(', ') || 'none'}`
+      )
+    }
+  }
+}
+
+export function validateAgentOverrides(
+  logger: InspectorLogger,
+  state: InspectorState | Omit<InspectorState, 'typesLookup'>,
+  modelConfig?: InspectorModelConfig
+): void {
+  const overrides = modelConfig?.agentOverrides ?? {}
+  const aliases = modelConfig?.models ?? {}
+  const agentNames = new Set(
+    Object.values(state.agents.agentsMeta).map((m) => m.name)
+  )
+
+  for (const [agentName, override] of Object.entries(overrides)) {
+    if (!agentNames.has(agentName)) {
+      logger.warn(`agentOverrides references unknown agent '${agentName}'`)
+    }
+    if (
+      override.model &&
+      !override.model.includes('/') &&
+      !aliases[override.model]
+    ) {
+      logger.critical(
+        ErrorCode.INVALID_MODEL,
+        `agentOverrides['${agentName}'].model uses alias '${override.model}' which is not defined in models.`
+      )
+    }
+  }
+}
+
+export function computeDiagnostics(state: InspectorState): void {
+  const diagnostics: InspectorDiagnostic[] = []
+
+  for (const [id, meta] of Object.entries(state.functions.meta)) {
+    if (meta.services && !meta.services.optimized) {
+      diagnostics.push({
+        code: ErrorCode.SERVICES_NOT_DESTRUCTURED,
+        message: `Function '${id}' does not destructure its services parameter, preventing tree-shaking optimization.`,
+        sourceFile: meta.pikkuFuncId,
+        position: 0,
+      })
+    }
+    if (meta.wires && !meta.wires.optimized) {
+      diagnostics.push({
+        code: ErrorCode.WIRES_NOT_DESTRUCTURED,
+        message: `Function '${id}' does not destructure its wires parameter, preventing tree-shaking optimization.`,
+        sourceFile: meta.pikkuFuncId,
+        position: 0,
+      })
+    }
+  }
+
+  for (const [id, def] of Object.entries(state.middleware.definitions)) {
+    if (def.services && !def.services.optimized) {
+      diagnostics.push({
+        code: ErrorCode.SERVICES_NOT_DESTRUCTURED,
+        message: `Middleware '${id}' does not destructure its services parameter, preventing tree-shaking optimization.`,
+        sourceFile: def.sourceFile,
+        position: def.position,
+      })
+    }
+    if (def.wires && !def.wires.optimized) {
+      diagnostics.push({
+        code: ErrorCode.WIRES_NOT_DESTRUCTURED,
+        message: `Middleware '${id}' does not destructure its wires parameter, preventing tree-shaking optimization.`,
+        sourceFile: def.sourceFile,
+        position: def.position,
+      })
+    }
+  }
+
+  for (const [id, def] of Object.entries(state.permissions.definitions)) {
+    if (def.services && !def.services.optimized) {
+      diagnostics.push({
+        code: ErrorCode.SERVICES_NOT_DESTRUCTURED,
+        message: `Permission '${id}' does not destructure its services parameter, preventing tree-shaking optimization.`,
+        sourceFile: def.sourceFile,
+        position: def.position,
+      })
+    }
+    if (def.wires && !def.wires.optimized) {
+      diagnostics.push({
+        code: ErrorCode.WIRES_NOT_DESTRUCTURED,
+        message: `Permission '${id}' does not destructure its wires parameter, preventing tree-shaking optimization.`,
+        sourceFile: def.sourceFile,
+        position: def.position,
+      })
+    }
   }
 
-  state.serviceMetadata = allMetadata
+  state.diagnostics = diagnostics
 }

package/src/utils/resolve-external-package.ts

@@ -0,0 +1,42 @@
+import * as ts from 'typescript'
+import { ExternalPackageConfig } from '../types.js'
+
+/**
+ * Resolve the external package name from an imported identifier.
+ * Checks if the identifier's import module specifier matches any
+ * configured external package.
+ *
+ * This is a general utility — any wire handler that processes a `func`
+ * property can use it to detect when the function comes from an
+ * external package.
+ */
+export const resolveExternalPackageName = (
+  identifier: ts.Identifier,
+  checker: ts.TypeChecker,
+  externalPackages?: Record<string, ExternalPackageConfig>
+): string | null => {
+  if (!externalPackages || Object.keys(externalPackages).length === 0) {
+    return null
+  }
+
+  const sym = checker.getSymbolAtLocation(identifier)
+  if (!sym) return null
+
+  const decl = sym.declarations?.[0]
+  if (!decl || !ts.isImportSpecifier(decl)) return null
+
+  // ImportSpecifier -> NamedImports -> ImportClause -> ImportDeclaration
+  const importDecl = decl.parent?.parent?.parent
+  if (!importDecl || !ts.isImportDeclaration(importDecl)) return null
+  if (!ts.isStringLiteral(importDecl.moduleSpecifier)) return null
+
+  const moduleSpecifier = importDecl.moduleSpecifier.text
+
+  for (const config of Object.values(externalPackages)) {
+    if (config.package === moduleSpecifier) {
+      return config.package
+    }
+  }
+
+  return null
+}

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

@@ -0,0 +1,42 @@
+import type { TypesMap } from '../types-map.js'
+import type { FunctionsMeta } from '@pikku/core'
+
+export function resolveFunctionIOTypes(
+  pikkuFuncId: string,
+  functionsMeta: FunctionsMeta,
+  typesMap: TypesMap,
+  requiredTypes: Set<string>
+): { inputType: string; outputType: string } {
+  const functionMeta = functionsMeta[pikkuFuncId]
+  if (!functionMeta) {
+    throw new Error(
+      `Function ${pikkuFuncId} not found in functionsMeta. Please check your configuration.`
+    )
+  }
+
+  const input = functionMeta.inputs ? functionMeta.inputs[0] : undefined
+  const output = functionMeta.outputs ? functionMeta.outputs[0] : undefined
+
+  let inputType = 'null'
+  if (input) {
+    try {
+      inputType = typesMap.getTypeMeta(input).uniqueName
+    } catch {
+      inputType = input
+    }
+  }
+
+  let outputType = 'null'
+  if (output) {
+    try {
+      outputType = typesMap.getTypeMeta(output).uniqueName
+    } catch {
+      outputType = output
+    }
+  }
+
+  requiredTypes.add(inputType)
+  requiredTypes.add(outputType)
+
+  return { inputType, outputType }
+}

package/src/utils/resolve-identifier.ts

@@ -0,0 +1,46 @@
+import * as ts from 'typescript'
+
+/**
+ * Resolve an identifier to its definition, optionally unwrapping
+ * known "define" wrapper functions (e.g. defineHTTPRoutes, defineCLICommands).
+ *
+ * When the identifier resolves to a variable whose initializer is a call
+ * to one of the `unwrapFunctionNames`, the first argument of that call
+ * is returned instead.
+ */
+export function resolveIdentifier(
+  node: ts.Identifier,
+  checker: ts.TypeChecker,
+  unwrapFunctionNames?: string[]
+): ts.Node | undefined {
+  const symbol = checker.getSymbolAtLocation(node)
+  if (!symbol) return undefined
+
+  // Handle aliased symbols (imports)
+  let resolvedSymbol = symbol
+  if (resolvedSymbol.flags & ts.SymbolFlags.Alias) {
+    resolvedSymbol = checker.getAliasedSymbol(resolvedSymbol) ?? resolvedSymbol
+  }
+
+  const decl =
+    resolvedSymbol.valueDeclaration || resolvedSymbol.declarations?.[0]
+  if (!decl) return undefined
+
+  // Follow to the actual value (handles imports, variable declarations)
+  if (ts.isVariableDeclaration(decl) && decl.initializer) {
+    // Check if it's a call to one of the unwrap functions
+    if (
+      ts.isCallExpression(decl.initializer) &&
+      unwrapFunctionNames &&
+      unwrapFunctionNames.length > 0
+    ) {
+      const expr = decl.initializer.expression
+      if (ts.isIdentifier(expr) && unwrapFunctionNames.includes(expr.text)) {
+        return decl.initializer.arguments[0]
+      }
+    }
+    return decl.initializer
+  }
+
+  return undefined
+}