@pikku/inspector 0.12.25 → 0.12.27

package/src/add/add-auth.ts

@@ -168,6 +168,20 @@ export const addAuth: AddWiring = (logger, node, _checker, state) => {
     state.auth.userStatelessSession = true
   }
 
+  // Same rule for the stateful variant: a user-registered global
+  // betterAuthSession(...) (custom mapSession/impersonation/apiKey) means the CLI
+  // must NOT auto-generate its own default one — the generated one runs first and
+  // pre-empts the user's via the `if (session) next()` short-circuit. Stateful
+  // analogue of the betterAuthStatelessSession skip above.
+  if (
+    ts.isIdentifier(expression) &&
+    expression.text === 'betterAuthSession' &&
+    !node.getSourceFile().fileName.endsWith('.gen.ts') &&
+    isInsideGlobalMiddlewareRegistration(node)
+  ) {
+    state.auth.hasUserSessionMiddleware = true
+  }
+
   if (!ts.isIdentifier(expression) || expression.text !== 'pikkuBetterAuth')
     return
 

package/src/add/add-functions.ts

@@ -913,7 +913,12 @@ export const addFunctions: AddWiring = (
   //   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
-  {
+  // Opt-in only: inferring every handler's return type (getReturnTypeOfSignature)
+  // is the single most expensive checker operation and dominates `pikku all`
+  // wall-clock. The classification leak scan is a security lint, not codegen, so
+  // it runs ONLY when explicitly requested (`pikku all --security`) — see the
+  // classificationCheck option. Default codegen skips it entirely.
+  if (options.classificationCheck) {
     const sig = checker.getSignatureFromDeclaration(handler)
     if (sig) {
       const rawRet = checker.getReturnTypeOfSignature(sig)

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

@@ -48,7 +48,9 @@ async function runInspect(sourceCode: string) {
   await writeFile(file, sourceCode)
   const { logger, criticals } = makeLogger()
   try {
-    await inspect(logger, [file], { rootDir: tmpDir })
+    // The data-classification leak scan is opt-in (off by default to keep it
+    // off the `pikku all` hot path); these tests exercise it, so enable it.
+    await inspect(logger, [file], { rootDir: tmpDir, classificationCheck: true })
   } finally {
     await rm(tmpDir, { recursive: true, force: true })
   }

package/src/inspector.ts

@@ -1,7 +1,7 @@
 import * as ts from 'typescript'
 import { performance } from 'perf_hooks'
 import { resolve } from 'path'
-import { visitSetup, visitRoutes } from './visit.js'
+import { visitSetup, visitFunctions, visitRoutes } from './visit.js'
 import { TypesMap } from './types-map.js'
 import type {
   InspectorState,
@@ -269,6 +269,12 @@ export const inspect = async (
   // node_modules under rootDir (e.g. a locally-installed addon) is a
   // dependency, not project source — scanning it double-counts the addon's
   // own application types (CoreConfig/Services/SingletonServices).
+  // Sort by file name so the sweeps populate state in a stable order. The
+  // program's own file order depends on glob + import-graph resolution, which
+  // varies run to run — leaving generated meta keys (and anything serialized
+  // in insertion order) non-reproducible across identical `pikku all` runs.
+  // Safe because function registration is a dedicated pass (visitFunctions)
+  // that completes before any order-sensitive wiring resolution in visitRoutes.
   const sourceFiles = program
     .getSourceFiles()
     .filter(
@@ -276,6 +282,9 @@ export const inspect = async (
         sf.fileName.startsWith(rootDir) &&
         !sf.fileName.includes('/node_modules/')
     )
+    .sort((a, b) =>
+      a.fileName < b.fileName ? -1 : a.fileName > b.fileName ? 1 : 0
+    )
   logger.debug(
     `Got source files in ${(performance.now() - startSourceFiles).toFixed(2)}ms`
   )
@@ -298,7 +307,20 @@ export const inspect = async (
   await loadAddonFunctionsMeta(logger, state)
 
   if (!options.setupOnly) {
-    // Second sweep: add all transports
+    // Function sweep: register every function before transports/wirings resolve
+    // them, so resolution doesn't depend on source-file order.
+    const startFunctions = performance.now()
+    for (const sourceFile of sourceFiles) {
+      const sourceOptions = { ...options, sourceFile }
+      ts.forEachChild(sourceFile, (child) =>
+        visitFunctions(logger, checker, child, state, sourceOptions)
+      )
+    }
+    logger.debug(
+      `Visit functions phase completed in ${(performance.now() - startFunctions).toFixed(0)}ms`
+    )
+
+    // Transport sweep: add all transports/wirings
     const startRoutes = performance.now()
     for (const sourceFile of sourceFiles) {
       const sourceOptions = { ...options, sourceFile }

package/src/types.ts

@@ -287,6 +287,13 @@ export type InspectorOptions = Partial<{
     tsconfig: string
     schemasFromTypes?: string[]
     schema?: { additionalProperties?: boolean }
+    /**
+     * Directory for the on-disk TS-schema cache. When set, generated TS schemas
+     * are persisted here keyed by a hash of the custom-types content, so a warm
+     * `pikku all` whose function types are unchanged skips ts-json-schema-generator
+     * entirely (the single largest cold-run cost). Omit to disable disk caching.
+     */
+    cacheDir?: string
   }
   openAPI: {
     additionalInfo: OpenAPISpecInfo
@@ -294,6 +301,12 @@ export type InspectorOptions = Partial<{
   tags: string[]
   manifest: VersionManifest
   oldProgram: ts.Program | undefined
+  /**
+   * Run the data-classification leak scan (Private/Pii/Secret brands in function
+   * return types). Off by default — it forces return-type inference on every
+   * function, which is expensive. Enabled via `pikku all --security`.
+   */
+  classificationCheck: boolean
 }>
 
 export interface InspectorLogger {
@@ -502,6 +515,12 @@ export interface InspectorState {
      *  own default-map stateless middleware, which would otherwise pre-empt the
      *  user's custom mapSession (pikkujs/pikku#754). */
     userStatelessSession?: boolean
+    /** True when a user (non-generated) file already registers a global
+     *  `betterAuthSession(...)`. The CLI then skips auto-generating its own
+     *  default stateful middleware, which would otherwise run first and pre-empt
+     *  the user's config (mapSession/impersonation/apiKey). Stateful analogue of
+     *  `userStatelessSession`. */
+    hasUserSessionMiddleware?: boolean
   }
   secrets: {
     definitions: SecretDefinitions

package/src/utils/extract-function-name.ts

@@ -1,7 +1,25 @@
 import * as ts from 'typescript'
-import { randomUUID } from 'crypto'
+import { createHash } from 'crypto'
+import { relative } from 'path'
 import { formatVersionedId } from '@pikku/core'
 
+/**
+ * Deterministic placeholder id for an anonymous/unnamed pikku function or
+ * permission. Derived from the call expression's source location (relative path
+ * + start position) so `pikku all` produces byte-identical output across runs —
+ * a `randomUUID()` here made generated meta non-reproducible. Still `__temp_`
+ * prefixed so downstream resolution (which keys off that prefix) is unchanged.
+ */
+function tempFuncId(callExpr: ts.Node, rootDir: string): string {
+  const sourceFile = callExpr.getSourceFile()
+  const relPath = relative(rootDir, sourceFile.fileName)
+  const hash = createHash('sha1')
+    .update(`${relPath}:${callExpr.getStart()}`)
+    .digest('hex')
+    .slice(0, 16)
+  return `__temp_${hash}`
+}
+
 export type ExtractedFunctionName = {
   pikkuFuncId: string
   name: string
@@ -126,7 +144,7 @@ export function extractFunctionName(
               }
 
               if (!result.pikkuFuncId) {
-                result.pikkuFuncId = `__temp_${randomUUID()}`
+                result.pikkuFuncId = tempFuncId(callExpr, rootDir)
               }
 
               populateNameByPriority(result)
@@ -440,7 +458,7 @@ export function extractFunctionName(
   } else if (result.exportedName) {
     result.pikkuFuncId = result.exportedName
   } else {
-    result.pikkuFuncId = `__temp_${randomUUID()}`
+    result.pikkuFuncId = tempFuncId(callExpr, rootDir)
   }
 
   if (result.version !== null) {

package/src/utils/schema-generator.ts

@@ -1,4 +1,6 @@
 import * as ts from 'typescript'
+import { createHash } from 'crypto'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
 import { dirname, join, resolve } from 'path'
 import { createGenerator, RootlessError } from 'ts-json-schema-generator'
 import { register } from 'tsx/esm/api'
@@ -74,6 +76,74 @@ let cachedTsconfigPath: string | undefined
 let cachedCustomTypesContent: string | undefined
 let cachedTSSchemas: Record<string, JSONValue> | undefined
 
+const SCHEMA_CACHE_VERSION = 1
+
+// This package's own version — folded into the cache key so that upgrading
+// @pikku/inspector (the channel through which a schema-format change ships)
+// auto-invalidates every on-disk cache, without relying on someone remembering
+// to bump SCHEMA_CACHE_VERSION. Read once; falls back to the constant if the
+// package.json can't be located (e.g. an unexpected bundling layout).
+const inspectorVersion: string = (() => {
+  try {
+    const pkgUrl = new URL('../../package.json', import.meta.url)
+    const pkg = JSON.parse(readFileSync(pkgUrl, 'utf-8'))
+    return typeof pkg.version === 'string' ? pkg.version : `v${SCHEMA_CACHE_VERSION}`
+  } catch {
+    return `v${SCHEMA_CACHE_VERSION}`
+  }
+})()
+
+// Key the TS-schema cache on everything that affects its output: the generated
+// custom-types source, the generator options that change schema shape, and the
+// inspector version (schema-format changes ship with a version bump).
+function tsSchemaCacheKey(
+  customTypesContent: string,
+  config: { schemasFromTypes?: string[]; schema?: { additionalProperties?: boolean } }
+): string {
+  return createHash('sha1')
+    .update(`v${SCHEMA_CACHE_VERSION}\0`)
+    .update(`pkg:${inspectorVersion}\0`)
+    .update(`ap:${config.schema?.additionalProperties ? 1 : 0}\0`)
+    .update(`ft:${(config.schemasFromTypes ?? []).join(',')}\0`)
+    .update(customTypesContent)
+    .digest('hex')
+}
+
+function schemaCacheFile(cacheDir: string): string {
+  return join(cacheDir, 'ts-schemas.json')
+}
+
+function readDiskTSSchemas(
+  logger: InspectorLogger,
+  cacheDir: string,
+  key: string
+): Record<string, JSONValue> | null {
+  const file = schemaCacheFile(cacheDir)
+  if (!existsSync(file)) return null
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf-8'))
+    if (parsed?.key === key && parsed.schemas) return parsed.schemas
+  } catch (e) {
+    logger.debug(`Ignoring unreadable TS-schema cache: ${(e as Error).message}`)
+  }
+  return null
+}
+
+function writeDiskTSSchemas(
+  logger: InspectorLogger,
+  cacheDir: string,
+  key: string,
+  schemas: Record<string, JSONValue>
+): void {
+  const file = schemaCacheFile(cacheDir)
+  try {
+    mkdirSync(dirname(file), { recursive: true })
+    writeFileSync(file, JSON.stringify({ key, schemas }))
+  } catch (e) {
+    logger.debug(`Failed to persist TS-schema cache: ${(e as Error).message}`)
+  }
+}
+
 function createProgramWithVirtualFile(
   tsconfig: string,
   virtualFilePath: string,
@@ -494,6 +564,7 @@ export async function generateAllSchemas(
     tsconfig: string
     schemasFromTypes?: string[]
     schema?: { additionalProperties?: boolean }
+    cacheDir?: string
   },
   state: InspectorState
 ): Promise<Record<string, JSONValue>> {
@@ -509,11 +580,28 @@ export async function generateAllSchemas(
     requiredTypes
   )
 
+  // Fast path: same process, types unchanged — reuse the in-memory result.
   if (cachedTSSchemas && cachedCustomTypesContent === customTypesContent) {
     logger.debug('Reusing cached TS schemas (types unchanged)')
     return { ...cachedTSSchemas, ...zodSchemas }
   }
 
+  // Disk path: a prior `pikku all` left a cache whose key matches the current
+  // custom types — load it and skip ts-json-schema-generator (the dominant
+  // cold-run cost). Zod schemas are always regenerated (cheap, ~1ms/schema).
+  const cacheKey = config.cacheDir
+    ? tsSchemaCacheKey(customTypesContent, config)
+    : null
+  if (config.cacheDir && cacheKey) {
+    const disk = readDiskTSSchemas(logger, config.cacheDir, cacheKey)
+    if (disk) {
+      logger.debug('Reusing on-disk TS schemas (types unchanged across runs)')
+      cachedCustomTypesContent = customTypesContent
+      cachedTSSchemas = disk
+      return { ...disk, ...zodSchemas }
+    }
+  }
+
   const tsSchemas = generateTSSchemas(
     logger,
     config.tsconfig,
@@ -529,5 +617,9 @@ export async function generateAllSchemas(
   cachedCustomTypesContent = customTypesContent
   cachedTSSchemas = tsSchemas
 
+  if (config.cacheDir && cacheKey) {
+    writeDiskTSSchemas(logger, config.cacheDir, cacheKey, tsSchemas)
+  }
+
   return { ...tsSchemas, ...zodSchemas }
 }

package/src/utils/workflow/derive-workflow-plan.test.ts

@@ -0,0 +1,122 @@
+import { strict as assert } from 'assert'
+import { describe, test } from 'node:test'
+import type { WorkflowStepMeta } from '@pikku/core/workflow'
+import { deriveWorkflowPlan } from './derive-workflow-plan.js'
+
+const rpc = (stepName: string, rpcName = 'rpc.fn'): WorkflowStepMeta =>
+  ({ type: 'rpc', stepName, rpcName }) as WorkflowStepMeta
+const sleep = (stepName: string): WorkflowStepMeta =>
+  ({ type: 'sleep', stepName }) as WorkflowStepMeta
+const inline = (stepName: string): WorkflowStepMeta =>
+  ({ type: 'inline', stepName }) as WorkflowStepMeta
+
+describe('deriveWorkflowPlan', () => {
+  test('linear workflow is deterministic with every step listed in order', () => {
+    const plan = deriveWorkflowPlan([rpc('a'), sleep('b'), inline('c')])
+    assert.equal(plan.deterministic, true)
+    assert.deepEqual(plan.plannedSteps, [
+      { stepName: 'a' },
+      { stepName: 'b' },
+      { stepName: 'c' },
+    ])
+  })
+
+  test('parallel group lists each child step', () => {
+    const plan = deriveWorkflowPlan([
+      rpc('a'),
+      {
+        type: 'parallel',
+        children: [rpc('p1'), rpc('p2')],
+      } as WorkflowStepMeta,
+    ])
+    assert.equal(plan.deterministic, true)
+    assert.deepEqual(plan.plannedSteps, [
+      { stepName: 'a' },
+      { stepName: 'p1' },
+      { stepName: 'p2' },
+    ])
+  })
+
+  test('branch is loopless: plannedSteps cover every arm but not deterministic', () => {
+    const plan = deriveWorkflowPlan([
+      rpc('start'),
+      {
+        type: 'branch',
+        branches: [{ condition: 'x', steps: [rpc('left')] }],
+        elseSteps: [rpc('right')],
+      } as WorkflowStepMeta,
+      rpc('end'),
+    ])
+    assert.equal(plan.deterministic, false, 'a branch picks a path at runtime')
+    assert.deepEqual(plan.plannedSteps, [
+      { stepName: 'start' },
+      { stepName: 'left' },
+      { stepName: 'right' },
+      { stepName: 'end' },
+    ])
+  })
+
+  test('switch is loopless: cases + default contribute steps, not deterministic', () => {
+    const plan = deriveWorkflowPlan([
+      {
+        type: 'switch',
+        expression: 'kind',
+        cases: [{ steps: [rpc('caseA')] }, { steps: [rpc('caseB')] }],
+        defaultSteps: [rpc('fallback')],
+      } as WorkflowStepMeta,
+    ])
+    assert.equal(plan.deterministic, false)
+    assert.deepEqual(plan.plannedSteps, [
+      { stepName: 'caseA' },
+      { stepName: 'caseB' },
+      { stepName: 'fallback' },
+    ])
+  })
+
+  test('fanout (loop) yields no plannedSteps and is not deterministic', () => {
+    const plan = deriveWorkflowPlan([
+      rpc('before'),
+      {
+        type: 'fanout',
+        stepName: 'each',
+        child: rpc('child'),
+        mode: 'parallel',
+      } as WorkflowStepMeta,
+    ])
+    assert.equal(plan.deterministic, false)
+    assert.equal(plan.plannedSteps, undefined, 'loop count is runtime-dependent')
+  })
+
+  test('a fanout nested inside a branch still suppresses the plan', () => {
+    const plan = deriveWorkflowPlan([
+      {
+        type: 'branch',
+        branches: [
+          {
+            condition: 'x',
+            steps: [
+              {
+                type: 'fanout',
+                stepName: 'each',
+                child: rpc('child'),
+                mode: 'serial',
+              } as WorkflowStepMeta,
+            ],
+          },
+        ],
+      } as WorkflowStepMeta,
+    ])
+    assert.equal(plan.deterministic, false)
+    assert.equal(plan.plannedSteps, undefined)
+  })
+
+  test('non-named steps (set/return/cancel) are skipped', () => {
+    const plan = deriveWorkflowPlan([
+      { type: 'set' } as WorkflowStepMeta,
+      rpc('a'),
+      { type: 'return' } as WorkflowStepMeta,
+    ])
+    assert.equal(plan.deterministic, true)
+    assert.deepEqual(plan.plannedSteps, [{ stepName: 'a' }])
+  })
+})

package/src/utils/workflow/derive-workflow-plan.ts

@@ -0,0 +1,90 @@
+import type {
+  WorkflowStepMeta,
+  WorkflowPlannedStep,
+} from '@pikku/core/workflow'
+
+/**
+ * Derive the static UI plan for a DSL workflow from its extracted step tree.
+ *
+ * `plannedSteps` is the ordered list of every named step the workflow can run,
+ * so a frontend can render the step skeleton up front without executing the
+ * workflow or hand-listing steps. It is populated whenever the workflow has NO
+ * loops (fanout) — loops make the step COUNT runtime-dependent, so a workflow
+ * containing any fanout gets neither field.
+ *
+ * `deterministic` is true only when the exact executed sequence is known up
+ * front: a flat list of named steps with no branches/switches (which pick a
+ * path at runtime) and no loops. A branchy-but-loopless workflow is therefore
+ * `deterministic: false` but still gets `plannedSteps` (the full set of
+ * possible steps, in source order).
+ */
+export function deriveWorkflowPlan(steps: WorkflowStepMeta[]): {
+  deterministic: boolean
+  plannedSteps?: WorkflowPlannedStep[]
+} {
+  if (containsLoop(steps)) {
+    return { deterministic: false }
+  }
+  return {
+    deterministic: !containsConditional(steps),
+    plannedSteps: collectNamedSteps(steps),
+  }
+}
+
+/** Any fanout (loop) anywhere in the tree — including inside branches/switches. */
+function containsLoop(steps: WorkflowStepMeta[]): boolean {
+  return steps.some((step) => {
+    switch (step.type) {
+      case 'fanout':
+        return true
+      case 'branch':
+        return (
+          step.branches.some((b) => containsLoop(b.steps)) ||
+          (step.elseSteps ? containsLoop(step.elseSteps) : false)
+        )
+      case 'switch':
+        return (
+          step.cases.some((c) => containsLoop(c.steps)) ||
+          (step.defaultSteps ? containsLoop(step.defaultSteps) : false)
+        )
+      default:
+        return false
+    }
+  })
+}
+
+/** Any branch/switch — the run takes a runtime-decided path. */
+function containsConditional(steps: WorkflowStepMeta[]): boolean {
+  return steps.some((step) => step.type === 'branch' || step.type === 'switch')
+}
+
+/** Flatten named steps (rpc/inline/sleep/parallel children) in source order. */
+function collectNamedSteps(steps: WorkflowStepMeta[]): WorkflowPlannedStep[] {
+  const planned: WorkflowPlannedStep[] = []
+  for (const step of steps) {
+    switch (step.type) {
+      case 'rpc':
+      case 'inline':
+      case 'sleep':
+        planned.push({ stepName: step.stepName })
+        break
+      case 'parallel':
+        for (const child of step.children) {
+          planned.push({ stepName: child.stepName })
+        }
+        break
+      case 'branch':
+        for (const b of step.branches) planned.push(...collectNamedSteps(b.steps))
+        if (step.elseSteps) planned.push(...collectNamedSteps(step.elseSteps))
+        break
+      case 'switch':
+        for (const c of step.cases) planned.push(...collectNamedSteps(c.steps))
+        if (step.defaultSteps) {
+          planned.push(...collectNamedSteps(step.defaultSteps))
+        }
+        break
+      // set / return / cancel / filter / arrayPredicate produce no named step
+    }
+  }
+  return planned
+}

package/src/utils/workflow/graph/finalize-workflows.ts

@@ -3,6 +3,7 @@ import { isVersionedId, formatVersionedId, parseVersionedId } from '@pikku/core'
 import type { SerializedWorkflowGraph } from './workflow-graph.types.js'
 import { canonicalJSON, hashString } from '../../hash.js'
 import { convertDslToGraph } from './convert-dsl-to-graph.js'
+import { deriveWorkflowPlan } from '../derive-workflow-plan.js'
 import type { InspectorState } from '../../../types.js'
 
 export function finalizeWorkflows(state: InspectorState): void {
@@ -14,6 +15,20 @@ export function finalizeWorkflows(state: InspectorState): void {
     stampVersionsOnGraph(graph, functionsMeta)
     computeStepHashes(graph, functionsMeta)
     graph.graphHash = computeGraphHash(graph)
+    // Predictable (loopless) DSL workflows carry their full step list so a UI
+    // can render the skeleton up front without executing the run. Only DSL is
+    // gated: a complex workflow's step tree is incomplete (inline JS branches
+    // aren't captured) and flattens loops into plain steps, so its plan would
+    // lie about determinism.
+    if (graph.source === 'dsl') {
+      const { deterministic, plannedSteps } = deriveWorkflowPlan(meta.steps)
+      graph.deterministic = deterministic
+      // Omit an empty list — a deterministic workflow with no plannedSteps is
+      // simply one with no named steps (e.g. a bare return).
+      if (plannedSteps?.length) {
+        graph.plannedSteps = plannedSteps
+      }
+    }
     workflows.graphMeta[name] = graph
   }
 

package/src/utils/workflow/graph/workflow-graph.types.ts

@@ -108,7 +108,11 @@ export type FlowType =
   | 'set'
 
 // Import and re-export context types from core
-import type { ContextVariable, WorkflowContext } from '@pikku/core/workflow'
+import type {
+  ContextVariable,
+  WorkflowContext,
+  WorkflowPlannedStep,
+} from '@pikku/core/workflow'
 
 export type { ContextVariable, WorkflowContext }
 
@@ -202,6 +206,19 @@ export interface SerializedWorkflowGraph {
   entryNodeIds: string[]
   /** Hash of graph topology (nodes, edges, input mappings) */
   graphHash?: string
+  /**
+   * True when the exact executed step sequence is known up front: a loopless
+   * DSL workflow with no branches/switches. Lets a UI render the run as a fixed
+   * pipeline. Loops (fanout) → omitted; branchy-but-loopless → false.
+   */
+  deterministic?: boolean
+  /**
+   * Every named step the workflow can run, in source order — so a frontend can
+   * render the step skeleton before the run starts. Populated for any loopless
+   * DSL workflow (a branchy one lists all possible steps); omitted when the step
+   * count is runtime-dependent (any fanout).
+   */
+  plannedSteps?: WorkflowPlannedStep[]
   /** Wire entry points (HTTP, channel, queue, etc.) that trigger this workflow */
   wires?: WorkflowWires
 }

package/src/visit.ts

@@ -100,6 +100,28 @@ export const visitSetup = (
   )
 }
 
+// Register every pikku function before transports/wirings are resolved, so that
+// resolution (e.g. a channel handler referencing a function defined in another
+// file) is independent of source-file traversal order. Runs between visitSetup
+// and visitRoutes.
+export const visitFunctions = (
+  logger: InspectorLogger,
+  checker: ts.TypeChecker,
+  node: ts.Node,
+  state: InspectorState,
+  options: InspectorOptions
+) => {
+  const nextOptions = ts.isSourceFile(node)
+    ? { ...options, sourceFile: node }
+    : options
+
+  addFunctions(logger, node, checker, state, nextOptions)
+
+  ts.forEachChild(node, (child) =>
+    visitFunctions(logger, checker, child, state, nextOptions)
+  )
+}
+
 export const visitRoutes = (
   logger: InspectorLogger,
   checker: ts.TypeChecker,
@@ -113,7 +135,9 @@ export const visitRoutes = (
 
   checkAddonBans(logger, node, checker, state, nextOptions)
 
-  addFunctions(logger, node, checker, state, nextOptions)
+  // NOTE: addFunctions runs in its own earlier pass (visitFunctions) so that
+  // every function is registered before any wiring (channels, CLI, etc.)
+  // resolves it — wiring resolution must not depend on source-file order.
   addAuth(logger, node, checker, state, nextOptions)
   addSecret(logger, node, checker, state, nextOptions)
   addCredential(logger, node, checker, state, nextOptions)