@pikku/inspector 0.12.11 → 0.12.13

package/src/add/add-functions.ts

@@ -14,10 +14,12 @@ import {
   getPropertyValue,
   getCommonWireMetaData,
 } from '../utils/get-property-value.js'
+import { canonicalJSON, hashString } from '../utils/hash.js'
 import { resolveMiddleware } from '../utils/middleware.js'
 import { resolvePermissions } from '../utils/permissions.js'
 import { extractWireNames } from '../utils/post-process.js'
 import { ErrorCode } from '../error-codes.js'
+import { findPiiPaths } from '../utils/check-pii-output.js'
 import type { NodeType } from '@pikku/core/node'
 
 const isValidVariableName = (name: string) => {
@@ -312,6 +314,29 @@ const areCompatibleFunctionIds = (
   return existingParsed.baseName === incomingParsed.baseName
 }
 
+function printNode(node: ts.Node): string {
+  return ts
+    .createPrinter({ removeComments: true })
+    .printNode(ts.EmitHint.Unspecified, node, node.getSourceFile())
+}
+
+function computeImplementationHash(args: {
+  wrapper: string
+  handler: ts.ArrowFunction | ts.FunctionExpression
+  objectNode?: ts.ObjectLiteralExpression
+  isDirectFunction: boolean
+}): string {
+  const { wrapper, handler, objectNode, isDirectFunction } = args
+  return hashString(
+    canonicalJSON({
+      wrapper,
+      isDirectFunction,
+      handler: printNode(handler),
+      config: objectNode ? printNode(objectNode) : null,
+    })
+  )
+}
+
 /**
  * Inspect pikkuFunc calls, extract input/output and first-arg destructuring,
  * then push into state.functions.meta.
@@ -566,7 +591,12 @@ export const addFunctions: AddWiring = (
   }
 
   if (version !== undefined) {
-    const baseName = explicitName || exportedName || pikkuFuncId
+    let baseName = explicitName || exportedName || pikkuFuncId
+    // Strip trailing VN suffix if it matches the version (e.g. getDataV1 + version:1 → getData@v1)
+    const vSuffix = `V${version}`
+    if (baseName.endsWith(vSuffix) && baseName.length > vSuffix.length) {
+      baseName = baseName.slice(0, -vSuffix.length)
+    }
     pikkuFuncId = formatVersionedId(baseName, version)
   }
 
@@ -853,6 +883,29 @@ export const addFunctions: AddWiring = (
     }
   }
 
+  // ── PII brand check ───────────────────────────────────────────────────────
+  // Walk the function body's ACTUAL inferred return type looking for Private<T>
+  // / Secret<T> brands (__pii__ property).  This runs for every function,
+  // including those with a Zod output schema, because the TS return type
+  // reflects what the body actually returns before any Zod coercion.
+  {
+    const sig = checker.getSignatureFromDeclaration(handler)
+    if (sig) {
+      const rawRet = checker.getReturnTypeOfSignature(sig)
+      const unwrapped = unwrapPromise(checker, rawRet)
+      const piiPaths = findPiiPaths(checker, unwrapped)
+      if (piiPaths.length > 0) {
+        logger.critical(
+          ErrorCode.PII_IN_OUTPUT,
+          `Function '${name}' exposes PII-classified field(s) in its return type: ` +
+            piiPaths.map((p) => `'${p}'`).join(', ') +
+            `.\n  Either strip these fields before returning or mark the column ` +
+            `@public in the migration if it is safe to expose.`
+        )
+      }
+    }
+  }
+
   // --- resolve middleware ---
   let middleware = objectNode
     ? resolveMiddleware(state, objectNode, tags, checker)
@@ -894,6 +947,12 @@ export const addFunctions: AddWiring = (
   }
 
   const sessionless = expression.text !== 'pikkuFunc'
+  const implementationHash = computeImplementationHash({
+    wrapper: expression.text,
+    handler,
+    objectNode,
+    isDirectFunction,
+  })
 
   state.functions.meta[pikkuFuncId] = {
     pikkuFuncId,
@@ -914,6 +973,7 @@ export const addFunctions: AddWiring = (
     deploy: deploy || undefined,
     approvalRequired: approvalRequired || undefined,
     approvalDescription: approvalDescription || undefined,
+    implementationHash,
     version,
     title,
     tags: tags || undefined,

package/src/add/add-gateway.ts

@@ -70,7 +70,11 @@ export const addGateway: AddWiring = (
   }
 
   const packageName = ts.isIdentifier(funcInitializer)
-    ? resolveAddonName(funcInitializer, checker, state.rpc.wireAddonDeclarations)
+    ? resolveAddonName(
+        funcInitializer,
+        checker,
+        state.rpc.wireAddonDeclarations
+      )
     : null
 
   if (!nameValue || !typeValue) {

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

@@ -273,12 +273,32 @@ export function registerHTTPRoute({
 
   const input = fnMeta.inputs?.[0] || null
 
-  // Validate that route params and query params exist in function input type
-  if (params.length > 0 || query.length > 0) {
-    const inputTypes = state.typesLookup.get(funcName)
+  const getRouteInputKeys = (): string[] | null => {
+    const targetFuncName = refAddonTarget ?? funcName
+    const inputTypes = state.typesLookup.get(targetFuncName)
     if (inputTypes && inputTypes.length > 0) {
-      const inputKeys = extractTypeKeys(inputTypes[0])
+      return extractTypeKeys(inputTypes[0])
+    }
+
+    const targetMeta = resolveFunctionMeta(state, targetFuncName)
+    if (targetMeta?.inputSchemaName) {
+      const schema = state.schemas[targetMeta.inputSchemaName] as any
+      const properties = schema?.properties
+      if (properties && typeof properties === 'object') {
+        return Object.keys(properties)
+      }
+    }
 
+    return null
+  }
+
+  // Validate that route params and query params exist in function input type
+  if (params.length > 0 || query.length > 0) {
+    const inputKeys = getRouteInputKeys()
+    if (!inputKeys) {
+      // Input shape isn't inspectable at this phase (e.g. addon ref or opaque handler).
+      // Skip param/query validation rather than emitting a false positive.
+    } else {
       // Check path params
       if (params.length > 0) {
         const missingParams = params.filter((p) => !inputKeys.includes(p))
@@ -286,7 +306,7 @@ export function registerHTTPRoute({
           logger.critical(
             ErrorCode.ROUTE_PARAM_MISMATCH,
             `Route '${fullRoute}' has path parameter(s) [${missingParams.join(', ')}] ` +
-              `not found in function '${funcName}' input type. ` +
+              `not found in function '${refAddonTarget ?? funcName}' input type. ` +
               `Input type has: [${inputKeys.join(', ')}]`
           )
           return
@@ -300,7 +320,7 @@ export function registerHTTPRoute({
           logger.critical(
             ErrorCode.ROUTE_QUERY_MISMATCH,
             `Route '${fullRoute}' has query parameter(s) [${missingQuery.join(', ')}] ` +
-              `not found in function '${funcName}' input type. ` +
+              `not found in function '${refAddonTarget ?? funcName}' input type. ` +
               `Input type has: [${inputKeys.join(', ')}]`
           )
           return

package/src/add/add-keyed-wiring.ts

@@ -1,5 +1,8 @@
 import * as ts from 'typescript'
-import { getPropertyValue } from '../utils/get-property-value.js'
+import {
+  getPropertyValue,
+  assertStringLiteralProperty,
+} from '../utils/get-property-value.js'
 import type { AddWiring, InspectorState } from '../types.js'
 import { ErrorCode } from '../error-codes.js'
 import { detectSchemaVendorOrError } from '../utils/detect-schema-vendor.js'
@@ -39,6 +42,9 @@ export const createAddKeyedWiring = (config: KeyedWiringConfig): AddWiring => {
     if (ts.isObjectLiteralExpression(firstArg)) {
       const obj = firstArg
 
+      assertStringLiteralProperty(obj, 'name', config.label, logger)
+      assertStringLiteralProperty(obj, config.idField, config.label, logger)
+
       const nameValue = getPropertyValue(obj, 'name') as string | null
       const displayNameValue = getPropertyValue(obj, 'displayName') as
         | string

package/src/add/add-mcp-prompt.ts

@@ -74,7 +74,11 @@ export const addMCPPrompt: AddWiring = (
     }
 
     const packageName = ts.isIdentifier(funcInitializer)
-      ? resolveAddonName(funcInitializer, checker, state.rpc.wireAddonDeclarations)
+      ? resolveAddonName(
+          funcInitializer,
+          checker,
+          state.rpc.wireAddonDeclarations
+        )
       : null
 
     ensureFunctionMetadata(

package/src/add/add-mcp-resource.ts

@@ -83,7 +83,11 @@ export const addMCPResource: AddWiring = (
     }
 
     const packageName = ts.isIdentifier(funcInitializer)
-      ? resolveAddonName(funcInitializer, checker, state.rpc.wireAddonDeclarations)
+      ? resolveAddonName(
+          funcInitializer,
+          checker,
+          state.rpc.wireAddonDeclarations
+        )
       : null
 
     ensureFunctionMetadata(

package/src/add/add-middleware.ts

@@ -245,7 +245,7 @@ export const addMiddleware: AddWiring = (logger, node, checker, state) => {
     return
   }
 
-  if (expression.text === 'addMiddleware') {
+  if (expression.text === 'addTagMiddleware') {
     const tagArg = args[0]
     const middlewareArrayArg = args[1]
 
@@ -257,13 +257,13 @@ export const addMiddleware: AddWiring = (logger, node, checker, state) => {
     }
 
     if (!tag) {
-      logger.warn(`• addMiddleware call without valid tag string`)
+      logger.warn(`• addTagMiddleware call without valid tag string`)
       return
     }
 
     if (!ts.isArrayLiteralExpression(middlewareArrayArg)) {
       logger.error(
-        `• addMiddleware('${tag}', ...) must have a literal array as second argument`
+        `• addTagMiddleware('${tag}', ...) must have a literal array as second argument`
       )
       return
     }
@@ -329,7 +329,7 @@ export const addMiddleware: AddWiring = (logger, node, checker, state) => {
     if (!isFactory && exportedName) {
       logger.warn(
         `• Middleware group '${exportedName}' for tag '${tag}' is not wrapped in a factory function. ` +
-          `For tree-shaking, use: export const ${exportedName} = () => addMiddleware('${tag}', [...])`
+          `For tree-shaking, use: export const ${exportedName} = () => addTagMiddleware('${tag}', [...])`
       )
     }
 
@@ -352,6 +352,43 @@ export const addMiddleware: AddWiring = (logger, node, checker, state) => {
     return
   }
 
+  if (expression.text === 'addGlobalMiddleware') {
+    const middlewareArrayArg = args[0]
+    if (
+      !middlewareArrayArg ||
+      !ts.isArrayLiteralExpression(middlewareArrayArg)
+    ) {
+      logger.error(
+        `• addGlobalMiddleware(...) must have a literal array as its only argument`
+      )
+      return
+    }
+    const refs = extractMiddlewareRefs(
+      middlewareArrayArg,
+      checker,
+      state.rootDir
+    )
+    const definitionIds = refs.map((r) => r.definitionId)
+    if (definitionIds.length > 0) {
+      renameTempDefinitions(state, definitionIds, 'global', 'middleware')
+    }
+    const sourceFile = node.getSourceFile().fileName
+    for (let i = 0; i < refs.length; i++) {
+      const instanceId = makeContextBasedId('global', 'middleware', String(i))
+      state.middleware.instances[instanceId] = {
+        definitionId: definitionIds[i],
+        sourceFile,
+        position: node.getStart(),
+        isFactoryCall: refs[i].isFactoryCall,
+      }
+    }
+    // Without this, bootstrap codegen's "import every file with a wire-call"
+    // pass skips middleware-only files and the registration never runs.
+    state.http.files.add(sourceFile)
+    logger.debug(`• Found global middleware group with ${refs.length} entries`)
+    return
+  }
+
   if (expression.text === 'addHTTPMiddleware') {
     const patternArg = args[0]
     const middlewareArrayArg = args[1]
@@ -452,6 +489,7 @@ export const addMiddleware: AddWiring = (logger, node, checker, state) => {
       instanceIds,
       isFactory,
     })
+    state.http.files.add(sourceFile)
 
     logger.debug(
       `• Found HTTP route middleware group: ${pattern} -> [${instanceIds.join(', ')}] (${isFactory ? 'factory' : 'direct'})`

package/src/add/add-permission.ts

@@ -45,7 +45,7 @@ function isInsidePermissionContainer(node: ts.Node): boolean {
       ts.isCallExpression(current) &&
       ts.isIdentifier(current.expression) &&
       (current.expression.text === 'pikkuPermissionFactory' ||
-        current.expression.text === 'addPermission' ||
+        current.expression.text === 'addTagPermission' ||
         current.expression.text === 'addHTTPPermission')
     ) {
       return true
@@ -338,9 +338,9 @@ export const addPermission: AddWiring = (logger, node, checker, state) => {
 
   // Handle addPermission('tag', [permission1, permission2])
   // Supports two patterns:
-  // 1. export const x = () => addPermission('tag', [...])  (factory - tree-shakeable)
-  // 2. export const x = addPermission('tag', [...])  (direct - no tree-shaking)
-  if (expression.text === 'addPermission') {
+  // 1. export const x = () => addTagPermission('tag', [...])  (factory - tree-shakeable)
+  // 2. export const x = addTagPermission('tag', [...])  (direct - no tree-shaking)
+  if (expression.text === 'addTagPermission') {
     const tagArg = args[0]
     const permissionsArrayArg = args[1]
 
@@ -353,7 +353,7 @@ export const addPermission: AddWiring = (logger, node, checker, state) => {
     }
 
     if (!tag) {
-      logger.warn(`• addPermission call without valid tag string`)
+      logger.warn(`• addTagPermission call without valid tag string`)
       return
     }
 
@@ -363,7 +363,7 @@ export const addPermission: AddWiring = (logger, node, checker, state) => {
       !ts.isObjectLiteralExpression(permissionsArrayArg)
     ) {
       logger.error(
-        `• addPermission('${tag}', ...) must have a literal array or object as second argument`
+        `• addTagPermission('${tag}', ...) must have a literal array or object as second argument`
       )
       return
     }
@@ -416,7 +416,7 @@ export const addPermission: AddWiring = (logger, node, checker, state) => {
     if (!isFactory && exportedName) {
       logger.warn(
         `• Permission group '${exportedName}' for tag '${tag}' is not wrapped in a factory function. ` +
-          `For tree-shaking, use: export const ${exportedName} = () => addPermission('${tag}', [...])`
+          `For tree-shaking, use: export const ${exportedName} = () => addTagPermission('${tag}', [...])`
       )
     }
 

package/src/add/add-schedule.ts

@@ -73,7 +73,11 @@ export const addSchedule: AddWiring = (
     }
 
     const packageName = ts.isIdentifier(funcInitializer)
-      ? resolveAddonName(funcInitializer, checker, state.rpc.wireAddonDeclarations)
+      ? resolveAddonName(
+          funcInitializer,
+          checker,
+          state.rpc.wireAddonDeclarations
+        )
       : null
 
     if (!nameValue || !scheduleValue) {

package/src/add/add-workflow-graph.ts

@@ -357,6 +357,8 @@ function extractGraphFromNewFormat(
       input: {},
       next: undefined,
       onError: undefined,
+      retries: undefined,
+      retryDelay: undefined,
     }
   }
 
@@ -382,6 +384,8 @@ function extractGraphFromNewFormat(
           nodes[nodeId].next = nodeConfig.next
           nodes[nodeId].onError = nodeConfig.onError
           nodes[nodeId].input = nodeConfig.input
+          nodes[nodeId].retries = nodeConfig.retries
+          nodes[nodeId].retryDelay = nodeConfig.retryDelay
         }
       }
     }
@@ -400,10 +404,14 @@ function extractNodeConfigFromObject(
   next: any
   onError: any
   input: Record<string, any>
+  retries: number | undefined
+  retryDelay: string | number | undefined
 } {
   let next: any = undefined
   let onError: any = undefined
   let input: Record<string, any> = {}
+  let retries: number | undefined = undefined
+  let retryDelay: string | number | undefined = undefined
 
   for (const prop of obj.properties) {
     if (!ts.isPropertyAssignment(prop) || !ts.isIdentifier(prop.name)) continue
@@ -416,10 +424,20 @@ function extractNodeConfigFromObject(
       onError = extractNextConfig(prop.initializer, checker)
     } else if (propName === 'input') {
       input = extractInputMapping(prop.initializer, checker)
+    } else if (propName === 'retries') {
+      if (ts.isNumericLiteral(prop.initializer)) {
+        retries = Number(prop.initializer.text)
+      }
+    } else if (propName === 'retryDelay') {
+      if (ts.isNumericLiteral(prop.initializer)) {
+        retryDelay = Number(prop.initializer.text)
+      } else if (ts.isStringLiteral(prop.initializer)) {
+        retryDelay = prop.initializer.text
+      }
     }
   }
 
-  return { next, onError, input }
+  return { next, onError, input, retries, retryDelay }
 }
 
 /**

package/src/add/pii-check.test.ts

@@ -0,0 +1,197 @@
+import { strict as assert } from 'assert'
+import { describe, test } from 'node:test'
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { inspect } from '../inspector.js'
+import { ErrorCode } from '../error-codes.js'
+import type { InspectorLogger } from '../types.js'
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+function makeLogger() {
+  const criticals: Array<{ code: ErrorCode; message: string }> = []
+  const logger: InspectorLogger = {
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    critical: (code, message) => criticals.push({ code, message }),
+    hasCriticalErrors: () => criticals.length > 0,
+  }
+  return { logger, criticals }
+}
+
+/**
+ * Inline Private<T>/Secret<T> definitions that the test source files use.
+ * Mirrors what schema.d.ts emits so the TypeScript program sees the correct
+ * structural brand type even without @pikku/core being importable from /tmp.
+ */
+const BRAND_TYPES = `
+type Private<T> = T & { readonly __pii__: 'private' }
+type Secret<T> = T & { readonly __pii__: 'secret' }
+`
+
+async function runInspect(sourceCode: string) {
+  const tmpDir = await mkdtemp(join(tmpdir(), 'pikku-pii-test-'))
+  const file = join(tmpDir, 'funcs.ts')
+  await writeFile(file, sourceCode)
+  const { logger, criticals } = makeLogger()
+  try {
+    await inspect(logger, [file], { rootDir: tmpDir })
+  } finally {
+    await rm(tmpDir, { recursive: true, force: true })
+  }
+  return criticals
+}
+
+// ── findPiiPaths unit tests via full inspect() round-trip ────────────────────
+
+describe('PII output check — PKU910', () => {
+  test('flags a top-level Private<string> field', async () => {
+    const criticals = await runInspect(`
+${BRAND_TYPES}
+import { pikkuFunc } from '@pikku/core'
+export const getUser = pikkuFunc({
+  func: async () => {
+    const email = 'test@example.com' as Private<string>
+    return { id: 1, email }
+  }
+})
+`)
+    const hit = criticals.find((c) => c.code === ErrorCode.PII_IN_OUTPUT)
+    assert.ok(hit, `Expected PKU910 but got: ${JSON.stringify(criticals)}`)
+    assert.match(hit.message, /email/)
+  })
+
+  test('flags a top-level Secret<string> field', async () => {
+    const criticals = await runInspect(`
+${BRAND_TYPES}
+import { pikkuFunc } from '@pikku/core'
+export const getToken = pikkuFunc({
+  func: async () => {
+    const token = 'abc' as Secret<string>
+    return { token }
+  }
+})
+`)
+    const hit = criticals.find((c) => c.code === ErrorCode.PII_IN_OUTPUT)
+    assert.ok(hit)
+    assert.match(hit.message, /token/)
+  })
+
+  test('flags a nested Private field', async () => {
+    const criticals = await runInspect(`
+${BRAND_TYPES}
+import { pikkuFunc } from '@pikku/core'
+export const getProfile = pikkuFunc({
+  func: async () => {
+    const email = 'x@y.com' as Private<string>
+    return { user: { id: 1, email } }
+  }
+})
+`)
+    const hit = criticals.find((c) => c.code === ErrorCode.PII_IN_OUTPUT)
+    assert.ok(hit)
+    assert.match(hit.message, /user\.email/)
+  })
+
+  test('does not flag a plain string return', async () => {
+    const criticals = await runInspect(`
+import { pikkuFunc } from '@pikku/core'
+export const getPublicData = pikkuFunc({
+  func: async () => ({ id: 1, status: 'active', count: 42 })
+})
+`)
+    const hit = criticals.find((c) => c.code === ErrorCode.PII_IN_OUTPUT)
+    assert.equal(hit, undefined, `Expected no PKU910 but got: ${JSON.stringify(hit)}`)
+  })
+
+  test('does not flag a void-returning function', async () => {
+    const criticals = await runInspect(`
+import { pikkuFunc } from '@pikku/core'
+export const doWork = pikkuFunc({
+  func: async () => { /* no return */ }
+})
+`)
+    const hit = criticals.find((c) => c.code === ErrorCode.PII_IN_OUTPUT)
+    assert.equal(hit, undefined)
+  })
+
+  test('flags a function that returns a typed alias with Private field', async () => {
+    const criticals = await runInspect(`
+${BRAND_TYPES}
+import { pikkuFunc } from '@pikku/core'
+type UserRow = { id: number; email: Private<string> }
+export const getUser = pikkuFunc({
+  func: async (): Promise<UserRow> => {
+    return { id: 1, email: 'x' as Private<string> }
+  }
+})
+`)
+    const hit = criticals.find((c) => c.code === ErrorCode.PII_IN_OUTPUT)
+    assert.ok(hit)
+    assert.match(hit.message, /email/)
+  })
+
+  test('flags across multiple functions in the same file', async () => {
+    const criticals = await runInspect(`
+${BRAND_TYPES}
+import { pikkuFunc } from '@pikku/core'
+export const getEmail = pikkuFunc({
+  func: async () => ({ email: 'x' as Private<string> })
+})
+export const getPhone = pikkuFunc({
+  func: async () => ({ phone: '555' as Private<string> })
+})
+export const getSafe = pikkuFunc({
+  func: async () => ({ name: 'Alice' })
+})
+`)
+    const hits = criticals.filter((c) => c.code === ErrorCode.PII_IN_OUTPUT)
+    assert.equal(hits.length, 2, `Expected 2 PKU910 but got ${hits.length}`)
+  })
+
+  test('flags branded values inside arrays', async () => {
+    const criticals = await runInspect(`
+${BRAND_TYPES}
+import { pikkuFunc } from '@pikku/core'
+export const getEmails = pikkuFunc({
+  func: async () => ({ emails: ['x@y.com' as Private<string>] })
+})
+`)
+    const hit = criticals.find((c) => c.code === ErrorCode.PII_IN_OUTPUT)
+    assert.ok(hit, `Expected PKU910 but got: ${JSON.stringify(criticals)}`)
+    assert.match(hit.message, /emails/)
+  })
+
+  test('flags branded values inside string-indexed records', async () => {
+    const criticals = await runInspect(`
+${BRAND_TYPES}
+import { pikkuFunc } from '@pikku/core'
+export const getMap = pikkuFunc({
+  func: async () => ({ byId: { a: 'x@y.com' as Private<string> } as Record<string, Private<string>> })
+})
+`)
+    const hit = criticals.find((c) => c.code === ErrorCode.PII_IN_OUTPUT)
+    assert.ok(hit, `Expected PKU910 but got: ${JSON.stringify(criticals)}`)
+    assert.match(hit.message, /byId/)
+  })
+
+  test('does not flag when branded field is stripped before return', async () => {
+    const criticals = await runInspect(`
+${BRAND_TYPES}
+import { pikkuFunc } from '@pikku/core'
+export const getUser = pikkuFunc({
+  func: async () => {
+    const raw: { email: Private<string> } = { email: 'x' as Private<string> }
+    const safe: { email: string } = { email: raw.email as string }
+    return safe
+  }
+})
+`)
+    // The explicit type annotation on 'safe' strips the brand from the inferred return type
+    const hit = criticals.find((c) => c.code === ErrorCode.PII_IN_OUTPUT)
+    assert.equal(hit, undefined)
+  })
+})