@pikku/inspector 0.12.21 → 0.12.23

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

@@ -0,0 +1,84 @@
+import * as ts from 'typescript'
+import type { AddWiring } from '../types.js'
+import { ErrorCode } from '../error-codes.js'
+
+/**
+ * Wiring helpers an addon must not call. Addons declare contracts with the
+ * define* helpers and export functions; the consuming app does the wiring via
+ * refHTTP / refChannel / refCLI. Service declarations remain allowed.
+ */
+const BANNED_WIRINGS = new Set([
+  'wireAddon',
+  'wireChannel',
+  'wireCLI',
+  'wireGateway',
+  'wireHTTP',
+  'wireHTTPRoutes',
+  'wireMCPPrompt',
+  'wireMCPResource',
+  'wireQueueWorker',
+  'wireScheduler',
+  'wireTrigger',
+  'wireTriggerSource',
+])
+
+const CONTRACT_DEFINERS = new Set([
+  'defineHTTPRoutes',
+  'defineChannelRoutes',
+  'defineCLICommands',
+])
+
+const hasHandlerProperty = (node: ts.Node): boolean => {
+  let found = false
+  const visit = (current: ts.Node) => {
+    if (found) return
+    if (
+      ts.isPropertyAssignment(current) &&
+      (ts.isIdentifier(current.name) || ts.isStringLiteral(current.name)) &&
+      (current.name.text === 'middleware' ||
+        current.name.text === 'permissions')
+    ) {
+      found = true
+      return
+    }
+    ts.forEachChild(current, visit)
+  }
+  visit(node)
+  return found
+}
+
+/**
+ * Enforce addon authoring rules. Only runs when inspecting an addon package
+ * (options.isAddon). Addons cannot wire transports, and their contracts cannot
+ * carry middleware or permissions — those are the consuming app's concern.
+ */
+export const checkAddonBans: AddWiring = (
+  logger,
+  node,
+  _checker,
+  _state,
+  options
+) => {
+  if (!options.isAddon) return
+  if (!ts.isCallExpression(node) || !ts.isIdentifier(node.expression)) return
+
+  const name = node.expression.text
+
+  if (BANNED_WIRINGS.has(name)) {
+    logger.critical(
+      ErrorCode.ADDON_WIRING_NOT_ALLOWED,
+      `Addons must not call '${name}'. Declare contracts with define* and export functions; the consuming app wires them via refHTTP / refChannel / refCLI.`
+    )
+    return
+  }
+
+  if (CONTRACT_DEFINERS.has(name)) {
+    const [arg] = node.arguments
+    if (arg && hasHandlerProperty(arg)) {
+      logger.critical(
+        ErrorCode.ADDON_CONTRACT_HANDLERS_NOT_ALLOWED,
+        `Addon contract '${name}' must not declare middleware or permissions — these are applied by the consuming app, not the addon.`
+      )
+    }
+  }
+}

package/src/add/add-auth.test.ts

@@ -13,6 +13,9 @@ const makeLogger = (criticals: Array<{ code: ErrorCode; message: string }>) =>
     info: () => {},
     warn: () => {},
     error: () => {},
+    diagnostic: ({ code, message }) => {
+      criticals.push({ code, message })
+    },
     critical: (code: ErrorCode, message: string) => {
       criticals.push({ code, message })
     },

package/src/add/add-channel.ts

@@ -21,6 +21,8 @@ import { resolveIdentifier } from '../utils/resolve-identifier.js'
 import { resolveFunctionMeta } from '../utils/resolve-function-meta.js'
 import { resolveAddonName } from '../utils/resolve-addon-package.js'
 import { validateAuthSessionless } from '../utils/validate-auth-sessionless.js'
+import { getExportedVariableName } from '../utils/get-exported-variable-name.js'
+import { resolveRefContract } from '../utils/resolve-ref-contract.js'
 
 /**
  * Safely get the "initializer" expression of a property-like AST node:
@@ -40,6 +42,16 @@ function getInitializerOf(
   return undefined
 }
 
+function getObjectPropertyName(
+  name: ts.PropertyName | undefined
+): string | null {
+  if (!name) return null
+  if (ts.isIdentifier(name)) return name.text
+  if (ts.isStringLiteral(name) || ts.isNumericLiteral(name)) return name.text
+  if (ts.isComputedPropertyName(name)) return null
+  return name.getText()
+}
+
 /**
  * Resolve a handler expression (Identifier, CallExpression, or { func })
  * into its underlying function name.
@@ -116,6 +128,27 @@ function getHandlerNameFromExpression(
   return null
 }
 
+function extractExportedChannelRoutes(
+  logger: {
+    error: (msg: string) => void
+    critical: (code: ErrorCode, msg: string) => void
+  },
+  routes: ts.ObjectLiteralExpression,
+  state: InspectorState,
+  checker: ts.TypeChecker
+): Record<string, ChannelMessageMeta> {
+  const wrapper = ts.factory.createObjectLiteralExpression([
+    ts.factory.createPropertyAssignment(
+      'onMessageWiring',
+      ts.factory.createObjectLiteralExpression([
+        ts.factory.createPropertyAssignment('contract', routes),
+      ])
+    ),
+  ])
+
+  return addMessagesRoutes(logger, wrapper, state, checker).contract ?? {}
+}
+
 /**
  * Build out the nested message-routes by looking up each handler
  * in state.functions.meta instead of re-inferring it here.
@@ -155,9 +188,24 @@ export function addMessagesRoutes(
       }
     }
 
+    const refContract = resolveRefContract(
+      chanInit,
+      'refChannel',
+      state.exportedContracts.addonChannel
+    )
+    if (refContract) {
+      const refChannelKey = getObjectPropertyName(chanElem.name)
+      if (!refChannelKey) continue
+      result[refChannelKey] = {
+        ...refContract.contract,
+      }
+      continue
+    }
+
     if (!ts.isObjectLiteralExpression(chanInit)) continue
 
-    const channelKey = chanElem.name!.getText()
+    const channelKey = getObjectPropertyName(chanElem.name)
+    if (!channelKey) continue
     result[channelKey] = {}
 
     for (const routeElem of chanInit.properties) {
@@ -168,11 +216,8 @@ export function addMessagesRoutes(
       const routeName = routeElem.name
       if (!routeName) continue
 
-      let routeKey = routeName.getText()
-      // For string literals like 'greet' or "greet", strip the quotes
-      if (ts.isStringLiteral(routeName)) {
-        routeKey = routeName.text
-      }
+      const routeKey = getObjectPropertyName(routeName)
+      if (!routeKey) continue
 
       // For shorthand properties, we need to resolve the identifier to its declaration
       if (ts.isShorthandPropertyAssignment(routeElem)) {
@@ -529,6 +574,18 @@ export const addChannel: AddWiring = (
   options
 ) => {
   if (!ts.isCallExpression(node)) return
+  if (
+    ts.isIdentifier(node.expression) &&
+    node.expression.text === 'defineChannelRoutes'
+  ) {
+    const exportName = getExportedVariableName(node, options.sourceFile)
+    const [firstArg] = node.arguments
+    if (exportName && firstArg && ts.isObjectLiteralExpression(firstArg)) {
+      state.exportedContracts.channel[exportName] =
+        extractExportedChannelRoutes(logger, firstArg, state, checker)
+    }
+    return
+  }
   const { expression, arguments: args } = node
   if (!ts.isIdentifier(expression) || expression.text !== 'wireChannel') return
   const first = args[0]
@@ -664,7 +721,9 @@ export const addChannel: AddWiring = (
     state.serviceAggregation.usedFunctions.add(message.pikkuFuncId)
   }
 
-  for (const channelHandlers of Object.values(messageWirings)) {
+  for (const channelHandlers of Object.values(
+    messageWirings as Record<string, Record<string, ChannelMessageMeta>>
+  )) {
     for (const handler of Object.values(channelHandlers)) {
       state.serviceAggregation.usedFunctions.add(handler.pikkuFuncId)
     }

package/src/add/add-cli-renderers.test.ts

@@ -12,6 +12,7 @@ const makeLogger = () =>
     info: () => {},
     warn: () => {},
     error: () => {},
+    diagnostic: () => {},
     critical: () => {},
     hasCriticalErrors: () => false,
   }) satisfies InspectorLogger

package/src/add/add-cli.ts

@@ -19,6 +19,8 @@ import { resolveIdentifier } from '../utils/resolve-identifier.js'
 import { resolveAddonName } from '../utils/resolve-addon-package.js'
 import { validateAuthSessionless } from '../utils/validate-auth-sessionless.js'
 import { extractServicesFromFunction } from '../utils/extract-services.js'
+import { getExportedVariableName } from '../utils/get-exported-variable-name.js'
+import { resolveRefContract } from '../utils/resolve-ref-contract.js'
 
 // Track if we've warned about missing Config type to avoid duplicate warnings
 const configTypeWarningShown = new Set<string>()
@@ -34,6 +36,25 @@ export const addCLI: AddWiring = (
   options
 ) => {
   if (!ts.isCallExpression(node)) return
+  if (
+    ts.isIdentifier(node.expression) &&
+    node.expression.text === 'defineCLICommands'
+  ) {
+    const exportName = getExportedVariableName(node, options.sourceFile)
+    const [firstArg] = node.arguments
+    if (exportName && firstArg && ts.isObjectLiteralExpression(firstArg)) {
+      inspectorState.exportedContracts.cli[exportName] = processCommands(
+        logger,
+        firstArg,
+        node.getSourceFile(),
+        typeChecker,
+        exportName,
+        inspectorState,
+        options
+      )
+    }
+    return
+  }
   // Check if this is a wireCLI call
   if (!node || !node.expression) {
     return
@@ -214,6 +235,15 @@ function processCommands(
           programTags
         )
         Object.assign(commands, spreadCommands)
+      } else {
+        const refCommands = resolveRefContract(
+          prop.expression,
+          'refCLI',
+          inspectorState.exportedContracts.addonCli
+        )
+        if (refCommands) {
+          Object.assign(commands, refCommands.contract)
+        }
       }
       continue
     }

package/src/add/add-functions.test.ts

@@ -39,6 +39,9 @@ describe('addFunctions duplicate name handling', () => {
       info: () => {},
       warn: () => {},
       error: () => {},
+      diagnostic: ({ code, message }) => {
+        criticals.push({ code, message })
+      },
       critical: (code: ErrorCode, message: string) => {
         criticals.push({ code, message })
       },
@@ -91,6 +94,9 @@ describe('addFunctions duplicate name handling', () => {
       info: () => {},
       warn: () => {},
       error: () => {},
+      diagnostic: ({ code, message }) => {
+        criticals.push({ code, message })
+      },
       critical: (code: ErrorCode, message: string) => {
         criticals.push({ code, message })
       },
@@ -142,6 +148,7 @@ describe('addFunctions duplicate name handling', () => {
       info: () => {},
       warn: () => {},
       error: () => {},
+      diagnostic: () => {},
       critical: () => {},
       hasCriticalErrors: () => false,
     }
@@ -204,6 +211,9 @@ describe('addFunctions duplicate name handling', () => {
       info: () => {},
       warn: () => {},
       error: () => {},
+      diagnostic: ({ code, message }) => {
+        criticals.push({ code, message })
+      },
       critical: (code: ErrorCode, message: string) => {
         criticals.push({ code, message })
       },
@@ -250,6 +260,7 @@ describe('addFunctions implementationHash', () => {
       info: () => {},
       warn: () => {},
       error: () => {},
+      diagnostic: () => {},
       critical: () => {},
       hasCriticalErrors: () => false,
     }
@@ -296,6 +307,7 @@ describe('addFunctions implementationHash', () => {
       info: () => {},
       warn: () => {},
       error: () => {},
+      diagnostic: () => {},
       critical: () => {},
       hasCriticalErrors: () => false,
     }
@@ -349,6 +361,7 @@ describe('pikkuChannelConnectionFunc generic mapping', () => {
       info: () => {},
       warn: () => {},
       error: () => {},
+      diagnostic: () => {},
       critical: () => {},
       hasCriticalErrors: () => false,
     }

package/src/add/add-functions.ts

@@ -931,23 +931,27 @@ export const addFunctions: AddWiring = (
         .map((f) => f.path)
 
       if (secretPaths.length > 0) {
-        logger.critical(
-          ErrorCode.PII_IN_OUTPUT,
-          `Function '${name}' exposes secret-classified field(s) in its return type: ` +
+        logger.diagnostic({
+          severity: 'error',
+          code: ErrorCode.PII_IN_OUTPUT,
+          message:
+            `Function '${name}' exposes secret-classified field(s) in its return type: ` +
             secretPaths.map((p) => `'${p}'`).join(', ') +
             `.\n  Secret fields must never appear in function output. ` +
-            `Strip these fields before returning or change the column classification.`
-        )
+            `Strip these fields before returning or change the column classification.`,
+        })
       }
 
       if (sessionless && privatePaths.length > 0) {
-        logger.critical(
-          ErrorCode.PII_IN_OUTPUT,
-          `Sessionless function '${name}' exposes private-classified field(s) in its return type: ` +
+        logger.diagnostic({
+          severity: 'error',
+          code: ErrorCode.PII_IN_OUTPUT,
+          message:
+            `Sessionless function '${name}' exposes private-classified field(s) in its return type: ` +
             privatePaths.map((p) => `'${p}'`).join(', ') +
             `.\n  Private fields are only safe to return from authenticated (sessioned) functions. ` +
-            `Either require a session (use pikkuFunc) or mark the column @public if it is safe to expose publicly.`
-        )
+            `Either require a session (use pikkuFunc) or mark the column @public if it is safe to expose publicly.`,
+        })
       }
     }
   }

package/src/add/add-http-route.ts

@@ -13,7 +13,11 @@ import {
   getPropertyAssignmentInitializer,
   extractTypeKeys,
 } from '../utils/type-utils.js'
-import type { AddWiring, InspectorState } from '../types.js'
+import type {
+  AddWiring,
+  ExportedHTTPRouteConfigMeta,
+  InspectorState,
+} from '../types.js'
 import { resolveHTTPMiddlewareFromObject } from '../utils/middleware.js'
 import { resolveHTTPPermissionsFromObject } from '../utils/permissions.js'
 import { extractWireNames } from '../utils/post-process.js'
@@ -40,6 +44,16 @@ export interface RegisterHTTPRouteParams {
   inheritedAuth?: boolean
 }
 
+export interface RegisterHTTPRouteMetaParams {
+  route: ExportedHTTPRouteConfigMeta
+  state: InspectorState
+  logger: InspectorLogger
+  sourceFile: ts.SourceFile
+  basePath?: string
+  inheritedTags?: string[]
+  inheritedAuth?: boolean
+}
+
 /**
  * Extract header schema reference from headers property
  */
@@ -421,6 +435,66 @@ export function registerHTTPRoute({
   }
 }
 
+export function registerHTTPRouteMeta({
+  route,
+  state,
+  logger,
+  sourceFile,
+  basePath = '',
+  inheritedTags = [],
+  inheritedAuth,
+}: RegisterHTTPRouteMetaParams): void {
+  const method = route.method.toLowerCase()
+  const fullRoute = basePath + route.route
+  const tags = [...inheritedTags, ...(route.tags || [])]
+  const funcName = route.func.pikkuFuncId
+  const fnMeta = resolveFunctionMeta(state, funcName)
+
+  if (!fnMeta) {
+    logger.critical(
+      ErrorCode.FUNCTION_METADATA_NOT_FOUND,
+      `No function metadata found for '${funcName}'.`
+    )
+    return
+  }
+
+  let params: string[] = []
+  try {
+    const keys = pathToRegexp(fullRoute).keys
+    params = keys.filter((k) => k.type === 'param').map((k) => k.name)
+  } catch (error) {
+    logger.error(
+      `Failed to parse route '${fullRoute}': ${error instanceof Error ? error.message : error}`
+    )
+    return
+  }
+
+  if (!route.func.packageName) {
+    computeInputTypes(
+      state.http.metaInputTypes,
+      method,
+      fnMeta.inputs?.[0] || null,
+      [],
+      params
+    )
+  }
+
+  state.serviceAggregation.usedFunctions.add(funcName)
+  state.http.files.add(sourceFile.fileName)
+  state.http.meta[method][fullRoute] = {
+    pikkuFuncId: funcName,
+    ...(route.func.packageName && { packageName: route.func.packageName }),
+    route: fullRoute,
+    sourceFile: sourceFile.fileName,
+    method: method as HTTPMethod,
+    params: params.length > 0 ? params : undefined,
+    inputTypes: undefined,
+    tags: tags.length > 0 ? tags : undefined,
+    sse: route.sse ? true : undefined,
+    groupBasePath: basePath || undefined,
+  }
+}
+
 /**
  * Process wireHTTP calls
  */