@pikku/inspector 0.12.14 → 0.12.17

package/dist/utils/schema-generator.js

@@ -212,7 +212,9 @@ async function batchImportWithRegister(logger, sourceFiles) {
         return null;
     }
     finally {
-        await unregister?.();
+        void Promise.resolve(unregister?.()).catch((e) => {
+            logger.debug(`tsx unregister() failed: ${e.message}`);
+        });
     }
 }
 async function importWithRegister(sourceFile) {
@@ -221,7 +223,7 @@ async function importWithRegister(sourceFile) {
         return await import(sourceFile);
     }
     finally {
-        await unregister();
+        void Promise.resolve(unregister()).catch(() => { });
     }
 }
 function processZodSchema(schemaName, zodSchema, schemas, typesMap, auxiliaryTypeStore, printer, fakeSourceFile, logger) {

package/dist/utils/workflow/dsl/extract-dsl-workflow.js

@@ -293,21 +293,32 @@ function extractExpressionStatement(statement, context) {
         if (ts.isIdentifier(expr.left)) {
             outputVar = expr.left.text;
             // Check if this is an assignment to a context variable (set step)
+            // But if the RHS is a workflow.do() call, fall through to RPC extraction —
+            // reassigning a pre-declared variable with a workflow step is valid and common.
             if (context.contextVars.has(outputVar)) {
-                const literalValue = extractLiteralValue(expr.right);
-                if (literalValue !== undefined) {
+                const rhs = expr.right;
+                const rhsCall = ts.isAwaitExpression(rhs) && ts.isCallExpression(rhs.expression)
+                    ? rhs.expression
+                    : null;
+                const isWorkflowCall = rhsCall
+                    ? isWorkflowDoCall(rhsCall, context.checker)
+                    : false;
+                if (!isWorkflowCall) {
+                    const literalValue = extractLiteralValue(expr.right);
+                    if (literalValue !== undefined) {
+                        return {
+                            type: 'set',
+                            variable: outputVar,
+                            value: literalValue,
+                        };
+                    }
+                    // Non-literal assignment to context var - use expression as string
                     return {
                         type: 'set',
                         variable: outputVar,
-                        value: literalValue,
+                        value: getSourceText(expr.right),
                     };
                 }
-                // Non-literal assignment to context var - use expression as string
-                return {
-                    type: 'set',
-                    variable: outputVar,
-                    value: getSourceText(expr.right),
-                };
             }
         }
         // Use right side as the expression to extract from
@@ -1029,6 +1040,29 @@ function extractReturn(statement, context) {
     if (!statement.expression) {
         return null;
     }
+    if (ts.isAwaitExpression(statement.expression) &&
+        ts.isCallExpression(statement.expression.expression)) {
+        const call = statement.expression.expression;
+        if (isWorkflowDoCall(call, context.checker)) {
+            return isInlineDoCall(call)
+                ? extractInlineStep(call, context)
+                : extractRpcStep(call, context);
+        }
+        if (isWorkflowSleepCall(call, context.checker)) {
+            return extractSleepStep(call, context);
+        }
+    }
+    if (ts.isCallExpression(statement.expression)) {
+        const call = statement.expression;
+        if (isWorkflowDoCall(call, context.checker)) {
+            return isInlineDoCall(call)
+                ? extractInlineStep(call, context)
+                : extractRpcStep(call, context);
+        }
+        if (isWorkflowSleepCall(call, context.checker)) {
+            return extractSleepStep(call, context);
+        }
+    }
     if (!ts.isObjectLiteralExpression(statement.expression)) {
         return null;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/inspector",
-  "version": "0.12.14",
+  "version": "0.12.17",
   "author": "yasser.fadl@gmail.com",
   "license": "BUSL-1.1",
   "type": "module",
@@ -35,7 +35,7 @@
   },
   "dependencies": {
     "@openapi-contrib/json-schema-to-openapi-schema": "^4.3.1",
-    "@pikku/core": "^0.12.27",
+    "@pikku/core": "^0.12.28",
     "path-to-regexp": "^8.3.0",
     "ts-json-schema-generator": "^2.5.0",
     "tsx": "^4.21.0",

package/src/add/add-ai-agent.ts

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

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

@@ -392,6 +392,7 @@ export const addFunctions: AddWiring = (
   let deploy: 'serverless' | 'server' | 'auto' | undefined
   let approvalRequired: boolean | undefined
   let approvalDescription: string | undefined
+  let inline: boolean | undefined
   let version: number | undefined
   let objectNode: ts.ObjectLiteralExpression | undefined
   let nodeDisplayName: string | null = null
@@ -462,7 +463,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
@@ -481,6 +488,7 @@ export const addFunctions: AddWiring = (
     approvalRequired = getPropertyValue(firstArg, 'approvalRequired') as
       | boolean
       | undefined
+    inline = getPropertyValue(firstArg, 'inline') as boolean | undefined
 
     // Extract approvalDescription identifier reference
     for (const prop of firstArg.properties) {
@@ -883,24 +891,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 +980,6 @@ export const addFunctions: AddWiring = (
     }
   }
 
-  const sessionless = expression.text !== 'pikkuFunc'
   const implementationHash = computeImplementationHash({
     wrapper: expression.text,
     handler,
@@ -973,6 +1006,7 @@ export const addFunctions: AddWiring = (
     deploy: deploy || undefined,
     approvalRequired: approvalRequired || undefined,
     approvalDescription: approvalDescription || undefined,
+    inline: inline === false ? false : undefined,
     implementationHash,
     version,
     title,

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