@pikku/inspector 0.12.14 → 0.12.16

package/src/add/add-channel.ts

@@ -238,7 +238,8 @@ export function addMessagesRoutes(
                             init,
                             'Channel message',
                             routeKey,
-                            logger
+                            logger,
+                            checker
                           ).tags
                         : undefined
                       const routeMiddleware = ts.isObjectLiteralExpression(init)
@@ -270,7 +271,8 @@ export function addMessagesRoutes(
                           init,
                           'Channel message',
                           routeKey,
-                          logger
+                          logger,
+                          checker
                         ).tags
                       : undefined
                     const routeMiddleware = ts.isObjectLiteralExpression(init)
@@ -319,7 +321,8 @@ export function addMessagesRoutes(
                                 init,
                                 'Channel message',
                                 routeKey,
-                                logger
+                                logger,
+                                checker
                               ).tags
                             : undefined
                           const routeMiddleware = ts.isObjectLiteralExpression(
@@ -350,7 +353,8 @@ export function addMessagesRoutes(
                                 init,
                                 'Channel message',
                                 routeKey,
-                                logger
+                                logger,
+                                checker
                               ).tags
                             : undefined
                           const routeMiddleware = ts.isObjectLiteralExpression(
@@ -438,7 +442,8 @@ export function addMessagesRoutes(
                       init,
                       'Channel message',
                       routeKey,
-                      logger
+                      logger,
+                      checker
                     ).tags
                   : undefined
                 const routeMiddleware = ts.isObjectLiteralExpression(init)
@@ -481,7 +486,13 @@ export function addMessagesRoutes(
       // Resolve middleware and permissions for this route
       // Check if the route config is an object literal with middleware/permissions
       const routeTags = ts.isObjectLiteralExpression(init)
-        ? getCommonWireMetaData(init, 'Channel message', routeKey, logger).tags
+        ? getCommonWireMetaData(
+            init,
+            'Channel message',
+            routeKey,
+            logger,
+            checker
+          ).tags
         : undefined
       const routeMiddleware = ts.isObjectLiteralExpression(init)
         ? resolveMiddleware(state, init, routeTags, checker)
@@ -540,7 +551,7 @@ export const addChannel: AddWiring = (
     : []
 
   const { disabled, tags, summary, description, errors } =
-    getCommonWireMetaData(obj, 'Channel', name, logger)
+    getCommonWireMetaData(obj, 'Channel', name, logger, checker)
 
   if (disabled) return
 
@@ -630,6 +641,25 @@ export const addChannel: AddWiring = (
     state.serviceAggregation.usedFunctions.add(disconnectFuncId)
   }
 
+  // Synthesize function meta for connect/disconnect handlers that are defined
+  // with pikkuChannelConnectionFunc/pikkuChannelDisconnectionFunc (not pikkuFunc/
+  // pikkuSessionlessFunc), so the runtime has correct sessionless info without
+  // needing to inject it at runtime.
+  {
+    const routeAuth = getPropertyValue(obj, 'auth')
+    const sessionless = routeAuth === false ? true : undefined
+    for (const funcId of [connectFuncId, disconnectFuncId]) {
+      if (funcId && !state.functions.meta[funcId]) {
+        state.functions.meta[funcId] = {
+          pikkuFuncId: funcId,
+          sessionless,
+          inputSchemaName: null,
+          outputSchemaName: null,
+        }
+      }
+    }
+  }
+
   if (message) {
     state.serviceAggregation.usedFunctions.add(message.pikkuFuncId)
   }

package/src/add/add-functions.ts

@@ -462,7 +462,13 @@ export const addFunctions: AddWiring = (
   // Extract config properties if using object form
   if (ts.isObjectLiteralExpression(firstArg)) {
     objectNode = firstArg
-    const metadata = getCommonWireMetaData(firstArg, 'Function', name, logger)
+    const metadata = getCommonWireMetaData(
+      firstArg,
+      'Function',
+      name,
+      logger,
+      checker
+    )
     if (metadata.disabled) return
     title = metadata.title
     tags = metadata.tags
@@ -883,24 +889,50 @@ export const addFunctions: AddWiring = (
     }
   }
 
-  // ── PII brand check ───────────────────────────────────────────────────────
-  // Walk the function body's ACTUAL inferred return type looking for Private<T>
-  // / Pii<T> / Secret<T> brands (__classification__ 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 sessionless = expression.text !== 'pikkuFunc'
+
+  // ── Classification brand check ─────────────────────────────────────────────
+  // Walk the function body's ACTUAL inferred return type looking for classification
+  // brands (__classification__ property on Private<T>, Pii<T>, Secret<T>).
+  //
+  // Semantics:
+  //   secret  → never returned by any exposed function (sessioned or not)
+  //   private → only visible to authenticated (sessioned) users; ok for pikkuFunc
+  //   public  → safe for sessionless functions
   {
     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) {
+      const classifiedFields = findPiiPaths(checker, unwrapped)
+
+      const secretPaths = classifiedFields
+        .filter((f) => f.classification === 'secret')
+        .map((f) => f.path)
+
+      const privatePaths = classifiedFields
+        .filter(
+          (f) => f.classification === 'private' || f.classification === 'pii'
+        )
+        .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: ` +
+            secretPaths.map((p) => `'${p}'`).join(', ') +
+            `.\n  Secret fields must never appear in function output. ` +
+            `Strip these fields before returning or change the column classification.`
+        )
+      }
+
+      if (sessionless && privatePaths.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.`
+          `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.`
         )
       }
     }
@@ -946,7 +978,6 @@ export const addFunctions: AddWiring = (
     }
   }
 
-  const sessionless = expression.text !== 'pikkuFunc'
   const implementationHash = computeImplementationHash({
     wrapper: expression.text,
     handler,

package/src/add/add-gateway.ts

@@ -45,7 +45,7 @@ export const addGateway: AddWiring = (
   const typeValue = getPropertyValue(obj, 'type') as GatewayTransportType | null
   const routeValue = getPropertyValue(obj, 'route') as string | undefined
   const { disabled, tags, summary, description, errors } =
-    getCommonWireMetaData(obj, 'Gateway', nameValue, logger)
+    getCommonWireMetaData(obj, 'Gateway', nameValue, logger, checker)
 
   if (disabled) return
 

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

@@ -175,7 +175,7 @@ export function registerHTTPRoute({
     summary,
     description,
     errors,
-  } = getCommonWireMetaData(obj, 'HTTP route', fullRoute, logger)
+  } = getCommonWireMetaData(obj, 'HTTP route', fullRoute, logger, checker)
 
   if (disabled) return
 
@@ -248,6 +248,31 @@ export function registerHTTPRoute({
     extracted.isHelper
   )
 
+  // Propagate sessionless from the addon target so the runtime can correctly
+  // determine whether a session is required for ref()-based routes.
+  if (refAddonTarget) {
+    const targetMeta = resolveFunctionMeta(state, refAddonTarget)
+    const inlineMeta = state.functions.meta[funcName]
+    if (targetMeta && inlineMeta && targetMeta.sessionless !== undefined) {
+      inlineMeta.sessionless = targetMeta.sessionless
+    }
+  }
+
+  // For inline functions (e.g. oauth2 handlers), propagate sessionless: true
+  // when auth is explicitly disabled at the route or group level — the
+  // developer opted out of auth so no session is required.
+  {
+    const inlineMeta = state.functions.meta[funcName]
+    if (inlineMeta && inlineMeta.sessionless === undefined) {
+      const routeAuth = getPropertyValue(obj, 'auth')
+      const resolvedAuth =
+        routeAuth === true || routeAuth === false ? routeAuth : inheritedAuth
+      if (resolvedAuth === false) {
+        inlineMeta.sessionless = true
+      }
+    }
+  }
+
   // Lookup existing function metadata
   const fnMeta = resolveFunctionMeta(state, funcName)
   if (!fnMeta) {

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

@@ -45,7 +45,7 @@ export const addMCPPrompt: AddWiring = (
 
     const nameValue = getPropertyValue(obj, 'name') as string | null
     const { disabled, tags, summary, description, errors } =
-      getCommonWireMetaData(obj, 'MCP prompt', nameValue, logger)
+      getCommonWireMetaData(obj, 'MCP prompt', nameValue, logger, checker)
 
     if (disabled) return
 

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

@@ -46,7 +46,7 @@ export const addMCPResource: AddWiring = (
     const uriValue = getPropertyValue(obj, 'uri') as string | null
     const titleValue = getPropertyValue(obj, 'title') as string | null
     const { disabled, tags, summary, description, errors } =
-      getCommonWireMetaData(obj, 'MCP resource', uriValue, logger)
+      getCommonWireMetaData(obj, 'MCP resource', uriValue, logger, checker)
 
     if (disabled) return
 

package/src/add/add-queue-worker.ts

@@ -37,7 +37,7 @@ export const addQueueWorker: AddWiring = (logger, node, checker, state) => {
 
     const name = getPropertyValue(obj, 'name') as string | null
     const { disabled, tags, summary, description, errors } =
-      getCommonWireMetaData(obj, 'Queue worker', name, logger)
+      getCommonWireMetaData(obj, 'Queue worker', name, logger, checker)
 
     if (disabled) return
 

package/src/add/add-schedule.ts

@@ -44,7 +44,7 @@ export const addSchedule: AddWiring = (
     const nameValue = getPropertyValue(obj, 'name') as string | null
     const scheduleValue = getPropertyValue(obj, 'schedule') as string | null
     const { disabled, tags, summary, description, errors } =
-      getCommonWireMetaData(obj, 'Scheduler', nameValue, logger)
+      getCommonWireMetaData(obj, 'Scheduler', nameValue, logger, checker)
 
     if (disabled) return
 

package/src/add/add-trigger.ts

@@ -55,7 +55,7 @@ const addWireTrigger: (
 
   const nameValue = getPropertyValue(obj, 'name') as string | null
   const { disabled, tags, summary, description, errors } =
-    getCommonWireMetaData(obj, 'Trigger', nameValue, logger)
+    getCommonWireMetaData(obj, 'Trigger', nameValue, logger, checker)
 
   if (disabled) return
 

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

@@ -0,0 +1,152 @@
+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 type { InspectorLogger } from '../types.js'
+
+function makeLogger(
+  criticals: Array<{ code: string; message: string }>
+): InspectorLogger {
+  return {
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    critical: (code: any, message: string) => {
+      criticals.push({ code, message })
+    },
+    hasCriticalErrors: () => criticals.length > 0,
+  }
+}
+
+describe('addWorkflow — workflow.do RPC detection', () => {
+  test('detects RPC step when result is assigned to a const', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-workflow-'))
+    const wfFile = join(rootDir, 'my.workflow.ts')
+    const stepFile = join(rootDir, 'my.steps.ts')
+
+    await writeFile(
+      stepFile,
+      [
+        "import { pikkuSessionlessFunc } from '@pikku/core'",
+        'export const doThing = pikkuSessionlessFunc({',
+        '  func: async ({ logger }) => ({ ok: true }),',
+        '})',
+      ].join('\n')
+    )
+
+    await writeFile(
+      wfFile,
+      [
+        "import { pikkuWorkflowFunc } from '@pikku/core/workflow'",
+        'export const myWorkflow = pikkuWorkflowFunc(async (_, _input, { workflow }) => {',
+        "  const result = await workflow.do('Do thing', 'doThing', {})",
+        '  return { id: result.ok }',
+        '})',
+      ].join('\n')
+    )
+
+    const criticals: Array<{ code: string; message: string }> = []
+    try {
+      const state = await inspect(makeLogger(criticals), [stepFile, wfFile], {
+        rootDir,
+      })
+      assert.ok(
+        state.rpc.invokedFunctions.has('doThing'),
+        'doThing should be in invokedFunctions'
+      )
+      assert.ok(
+        state.rpc.internalFiles.has('doThing'),
+        'doThing should be in internalFiles'
+      )
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+
+  test('detects RPC step when result is reassigned to a pre-declared null variable', async () => {
+    // Regression: `let x = null; x = await workflow.do(...)` was treated as a
+    // set-step instead of an RPC step, so the referenced function was never registered.
+    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-workflow-reassign-'))
+    const wfFile = join(rootDir, 'project.workflow.ts')
+    const stepFile = join(rootDir, 'project.steps.ts')
+
+    await writeFile(
+      stepFile,
+      [
+        "import { pikkuSessionlessFunc } from '@pikku/core'",
+        'export const launchSandbox = pikkuSessionlessFunc({',
+        '  func: async ({ logger }) => ({ sandboxId: "abc" }),',
+        '})',
+      ].join('\n')
+    )
+
+    await writeFile(
+      wfFile,
+      [
+        "import { pikkuWorkflowFunc } from '@pikku/core/workflow'",
+        'export const createProjectWorkflow = pikkuWorkflowFunc(async (_, input, { workflow }) => {',
+        '  let launched: { sandboxId: string } | null = null',
+        '  if (input.createSandbox) {',
+        "    launched = await workflow.do('Launch sandbox', 'launchSandbox', { projectId: input.projectId })",
+        '  }',
+        '  return { sandboxId: launched?.sandboxId ?? null }',
+        '})',
+      ].join('\n')
+    )
+
+    const criticals: Array<{ code: string; message: string }> = []
+    try {
+      const state = await inspect(makeLogger(criticals), [stepFile, wfFile], {
+        rootDir,
+      })
+      assert.ok(
+        state.rpc.invokedFunctions.has('launchSandbox'),
+        'launchSandbox should be in invokedFunctions even when assigned to a pre-declared null variable'
+      )
+      assert.ok(
+        state.rpc.internalFiles.has('launchSandbox'),
+        'launchSandbox should be in internalFiles so it gets registered in pikku-functions.gen.ts'
+      )
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+
+  test('still treats plain reassignment to context var as a set step', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-workflow-set-'))
+    const wfFile = join(rootDir, 'set.workflow.ts')
+
+    await writeFile(
+      wfFile,
+      [
+        "import { pikkuWorkflowFunc } from '@pikku/core/workflow'",
+        'export const setWorkflow = pikkuWorkflowFunc(async (_, input, { workflow }) => {',
+        '  let status = "pending"',
+        '  status = "done"',
+        "  await workflow.do('No-op', 'noopStep', {})",
+        '  return { status }',
+        '})',
+      ].join('\n')
+    )
+
+    const criticals: Array<{ code: string; message: string }> = []
+    try {
+      const state = await inspect(makeLogger(criticals), [wfFile], { rootDir })
+      const meta = state.workflows.meta['setWorkflow']
+      assert.ok(meta, 'workflow should be registered')
+      const steps = meta.steps ?? []
+      const setStep = steps.find(
+        (s: any) => s.type === 'set' && s.variable === 'status'
+      )
+      assert.ok(
+        setStep,
+        'plain string reassignment should still produce a set step'
+      )
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+})

package/src/add/add-workflow.ts

@@ -217,7 +217,8 @@ export const addWorkflow: AddWiring = (logger, node, checker, state) => {
       firstArg,
       'Workflow',
       workflowName,
-      logger
+      logger,
+      checker
     )
     if (metadata.disabled) return
     tags = metadata.tags

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

@@ -46,30 +46,35 @@ async function runInspect(sourceCode: string) {
   return criticals
 }
 
-// ── findPiiPaths unit tests via full inspect() round-trip ────────────────────
+// ── classification semantics:
+//   secret  → never returned by any function (sessioned or not)
+//   private → only blocked in sessionless functions (pikkuSessionlessFunc)
+//   public  → safe for sessionless functions
 
 describe('PII output check — PKU910', () => {
-  test('flags a top-level Private<string> field', async () => {
+  // ── Secret<T>: always blocked ──────────────────────────────────────────────
+
+  test('flags a top-level Secret<string> field in a sessioned function', async () => {
     const criticals = await runInspect(`
 ${BRAND_TYPES}
 import { pikkuFunc } from '@pikku/core'
-export const getUser = pikkuFunc({
+export const getToken = pikkuFunc({
   func: async () => {
-    const email = 'test@example.com' as Private<string>
-    return { id: 1, email }
+    const token = 'abc' as Secret<string>
+    return { token }
   }
 })
 `)
     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/)
+    assert.ok(hit)
+    assert.match(hit.message, /token/)
   })
 
-  test('flags a top-level Secret<string> field', async () => {
+  test('flags a top-level Secret<string> field in a sessionless function', async () => {
     const criticals = await runInspect(`
 ${BRAND_TYPES}
-import { pikkuFunc } from '@pikku/core'
-export const getToken = pikkuFunc({
+import { pikkuSessionlessFunc } from '@pikku/core'
+export const getToken = pikkuSessionlessFunc({
   func: async () => {
     const token = 'abc' as Secret<string>
     return { token }
@@ -81,11 +86,48 @@ export const getToken = pikkuFunc({
     assert.match(hit.message, /token/)
   })
 
-  test('flags a nested Private field', async () => {
+  // ── Private<T>: only blocked in sessionless functions ─────────────────────
+
+  test('flags a top-level Private<string> field in a sessionless function', async () => {
+    const criticals = await runInspect(`
+${BRAND_TYPES}
+import { pikkuSessionlessFunc } from '@pikku/core'
+export const getUser = pikkuSessionlessFunc({
+  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('does not flag a Private<string> field in a sessioned function', async () => {
     const criticals = await runInspect(`
 ${BRAND_TYPES}
 import { pikkuFunc } from '@pikku/core'
-export const getProfile = pikkuFunc({
+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.equal(
+      hit,
+      undefined,
+      `Expected no PKU910 (sessioned function may return Private fields) but got: ${JSON.stringify(hit)}`
+    )
+  })
+
+  test('flags a nested Private field in a sessionless function', async () => {
+    const criticals = await runInspect(`
+${BRAND_TYPES}
+import { pikkuSessionlessFunc } from '@pikku/core'
+export const getProfile = pikkuSessionlessFunc({
   func: async () => {
     const email = 'x@y.com' as Private<string>
     return { user: { id: 1, email } }
@@ -123,12 +165,12 @@ export const doWork = pikkuFunc({
     assert.equal(hit, undefined)
   })
 
-  test('flags a function that returns a typed alias with Private field', async () => {
+  test('flags a sessionless function that returns a typed alias with Private field', async () => {
     const criticals = await runInspect(`
 ${BRAND_TYPES}
-import { pikkuFunc } from '@pikku/core'
+import { pikkuSessionlessFunc } from '@pikku/core'
 type UserRow = { id: number; email: Private<string> }
-export const getUser = pikkuFunc({
+export const getUser = pikkuSessionlessFunc({
   func: async (): Promise<UserRow> => {
     return { id: 1, email: 'x' as Private<string> }
   }
@@ -139,17 +181,17 @@ export const getUser = pikkuFunc({
     assert.match(hit.message, /email/)
   })
 
-  test('flags across multiple functions in the same file', async () => {
+  test('flags across multiple sessionless functions in the same file', async () => {
     const criticals = await runInspect(`
 ${BRAND_TYPES}
-import { pikkuFunc } from '@pikku/core'
-export const getEmail = pikkuFunc({
+import { pikkuSessionlessFunc } from '@pikku/core'
+export const getEmail = pikkuSessionlessFunc({
   func: async () => ({ email: 'x' as Private<string> })
 })
-export const getPhone = pikkuFunc({
+export const getPhone = pikkuSessionlessFunc({
   func: async () => ({ phone: '555' as Private<string> })
 })
-export const getSafe = pikkuFunc({
+export const getSafe = pikkuSessionlessFunc({
   func: async () => ({ name: 'Alice' })
 })
 `)
@@ -157,11 +199,11 @@ export const getSafe = pikkuFunc({
     assert.equal(hits.length, 2, `Expected 2 PKU910 but got ${hits.length}`)
   })
 
-  test('flags branded values inside arrays', async () => {
+  test('flags branded values inside arrays (sessionless)', async () => {
     const criticals = await runInspect(`
 ${BRAND_TYPES}
-import { pikkuFunc } from '@pikku/core'
-export const getEmails = pikkuFunc({
+import { pikkuSessionlessFunc } from '@pikku/core'
+export const getEmails = pikkuSessionlessFunc({
   func: async () => ({ emails: ['x@y.com' as Private<string>] })
 })
 `)
@@ -170,11 +212,11 @@ export const getEmails = pikkuFunc({
     assert.match(hit.message, /emails/)
   })
 
-  test('flags branded values inside string-indexed records', async () => {
+  test('flags branded values inside string-indexed records (sessionless)', async () => {
     const criticals = await runInspect(`
 ${BRAND_TYPES}
-import { pikkuFunc } from '@pikku/core'
-export const getMap = pikkuFunc({
+import { pikkuSessionlessFunc } from '@pikku/core'
+export const getMap = pikkuSessionlessFunc({
   func: async () => ({ byId: { a: 'x@y.com' as Private<string> } as Record<string, Private<string>> })
 })
 `)
@@ -186,8 +228,8 @@ export const getMap = pikkuFunc({
   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({
+import { pikkuSessionlessFunc } from '@pikku/core'
+export const getUser = pikkuSessionlessFunc({
   func: async () => {
     const raw: { email: Private<string> } = { email: 'x' as Private<string> }
     const safe: { email: string } = { email: raw.email as string }