@pikku/inspector 0.12.25 → 0.12.27

package/CHANGELOG.md

@@ -1,3 +1,105 @@
+## 0.12.27
+
+### Patch Changes
+
+- 41ff485: fix(inspector): register functions in a dedicated pass before wiring resolution
+
+  The deterministic-codegen change sorted `program.getSourceFiles()` so generated
+  output is byte-identical across runs. But function registration (`addFunctions`)
+  ran in the same sweep as wiring resolution (`visitRoutes`), so once traversal
+  became alphabetical, a wiring file could be visited before the file that defines
+  the function it references — e.g. an addon contract (`hello.contracts.ts`)
+  before `hello.functions.ts` — producing a spurious `PKU559` ("No function
+  metadata found for channel handler").
+
+  Function registration now runs in its own pass (`visitFunctions`) over the
+  sorted files, completing before any transport/wiring resolution, so resolution
+  no longer depends on source-file order. Also sort the `register.gen.ts` schema
+  imports (driven by a `Set`) so that file is stable too, and opt the PII-check
+  tests into the now-opt-in classification scan.
+
+- d2078c8: fix(inspector): make codegen output deterministic across runs
+
+  Two sources of non-reproducible `pikku all` output are fixed:
+  1. **Random placeholder ids.** Anonymous/unnamed functions and inline (non-exported) permissions were given a `__temp_${randomUUID()}` id, so a referenced-but-not-exported `pikkuPermission` const (e.g. `permissions: { admin: [requiresPlatformAdmin] }`) produced a fresh UUID in the generated meta on every run. The placeholder is now derived deterministically from the call expression's source location (relative path + start offset), still `__temp_`-prefixed so downstream name resolution is unchanged.
+  2. **Unstable file-traversal order.** The two inspector sweeps iterated `program.getSourceFiles()` in glob + import-graph order, which varies run to run, so meta keys (and anything serialized in insertion order) were emitted in a different order each time — making a plain `git diff` of generated files look like functions were appearing/vanishing when the set was identical. Source files are now sorted by file name before the sweeps.
+
+  Net effect: byte-identical generated output across repeated runs with no source changes (verified across the full `.pikku` tree of a 331-function project).
+
+- e6fd12b: perf(inspector,cli): persist generated TS schemas to disk across runs
+
+  `generateAllSchemas` already cached its `ts-json-schema-generator` output
+  in-memory (keyed by the generated custom-types content), so the 2nd and 3rd
+  inspector passes within a single `pikku all` were near-free. But the cache
+  never survived the process, so every fresh `pikku all` paid the full cold cost
+  of building a second TS program + running ts-json-schema-generator — on a
+  331-function project that's ~2.2s, the single largest line item of a run.
+
+  The cache is now also persisted to disk (`node_modules/.cache/pikku/ts-schemas.json`,
+  gitignored by convention), keyed by a hash of the custom-types content plus the
+  generator options that affect output. A warm `pikku all` whose function types
+  are unchanged loads the schemas from disk and skips schema generation entirely;
+  the cold first pass drops by ~3.4s in practice (it also primes the in-memory
+  cache for the re-inspect passes). Zod schemas are still regenerated every run
+  (already ~1ms each). Output is byte-identical to a cold run (verified across the
+  full generated tree). The key is derived from the same content the in-memory
+  cache uses, so any type change busts it. It also folds in the `@pikku/inspector`
+  package version, so upgrading the inspector (the channel a schema-format change
+  ships through) auto-invalidates every cache; `SCHEMA_CACHE_VERSION` remains a
+  manual lever for in-development format changes between releases.
+
+  Opt-out: omit `schemaConfig.cacheDir` (the CLI sets it by default).
+
+- 244d892: perf(cli,inspector): make the data-classification scan opt-in (`pikku all --security`)
+
+  `pikku all` was spending the bulk of its wall-clock on the data-classification
+  leak check. For every function, on every inspector pass, it called
+  `checker.getReturnTypeOfSignature` to infer the handler's return type and scan it
+  for `Private`/`Pii`/`Secret` brands — the single most expensive type-checker
+  operation. On a 331-function project that was ~7.3s (≈half the total), repeated
+  across all three inspector passes, even though the scan only emits diagnostics
+  and never affects generated output.
+
+  The scan is a security lint, not codegen, so it's now **off by default** and gated
+  behind a new `--security` flag (or `security: true` in the config). A plain
+  `pikku all` skips return-type inference entirely; run `pikku all --security`
+  (optionally with `--fail-on-error`) in CI/pre-deploy to enforce it. On the
+  331-function project this cut `pikku all` from ~15.3s to ~9.6s.
+
+  Also: the `all` command now reads back the run's recorded per-step durations and,
+  under `PIKKU_TIMING=1`, prints a slowest-first timing table — making it easy to
+  see where codegen time goes without adding any hot-path instrumentation.
+
+- 940c253: Populate `plannedSteps` and `deterministic` on serialized DSL workflow graphs. For a DSL workflow with no loops (fanout), the inspector now records every named step in source order, so a UI can render the run's step skeleton up front without executing it or hand-listing steps. `deterministic` is `true` only for a flat, loopless, branch-free workflow (exact sequence known ahead of time); a branchy-but-loopless workflow lists all possible steps with `deterministic: false`; any fanout makes the count runtime-dependent so neither field is emitted (just `deterministic: false`). Only `source: 'dsl'` workflows are planned — `complex` step trees omit inline branches and flatten loops, so their plans would misreport determinism. The runtime already threads these fields from workflow meta onto each run via `getRun`.
+- Updated dependencies [4be205f]
+- Updated dependencies [061c717]
+- Updated dependencies [2c55e13]
+- Updated dependencies [c745c26]
+- Updated dependencies [57900b5]
+- Updated dependencies [72694f6]
+  - @pikku/core@0.12.39
+
+## 0.12.26
+
+### Patch Changes
+
+- ed548d5: fix(auth): skip the generated global `betterAuthSession()` when the user registers their own
+
+  The CLI's `auth.gen.ts` unconditionally wired a global
+  `addHTTPMiddleware('*', [betterAuthSession()])` (default map) on the stateful
+  path. A project that needs a customized session bridge — `mapSession`,
+  `impersonation`, `apiKey` — had to register a second global
+  `betterAuthSession({...})`, leaving two in the chain; the generated default ran
+  first and short-circuited (`if (session) next()`) so the custom one never took
+  effect.
+
+  The inspector now records `state.auth.hasUserSessionMiddleware` when it sees a
+  user-authored **global** `betterAuthSession` registration (route-scoped and
+  `.gen.ts` registrations are ignored, so regeneration never self-suppresses).
+  The CLI omits its own global `betterAuthSession()` from `auth.gen.ts` when that
+  flag is set — exactly one session bridge in the chain, the user's. Mirrors the
+  existing stateless skip (`userStatelessSession`, #754).
+
 ## 0.12.25
 
 ### Patch Changes

package/dist/add/add-auth.js

@@ -137,6 +137,17 @@ export const addAuth = (logger, node, _checker, state) => {
         isInsideGlobalMiddlewareRegistration(node)) {
         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;
     const sourceFile = node.getSourceFile().fileName;

package/dist/add/add-functions.js

@@ -647,7 +647,12 @@ export const addFunctions = (logger, node, checker, state, options) => {
     //   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/dist/inspector.js

@@ -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 { getFilesAndMethods } from './utils/get-files-and-methods.js';
 import { findCommonAncestor } from './utils/find-root-dir.js';
@@ -222,10 +222,17 @@ export const inspect = async (logger, routeFiles, options = {}) => {
     // 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((sf) => sf.fileName.startsWith(rootDir) &&
-        !sf.fileName.includes('/node_modules/'));
+        !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`);
     const state = getInitialInspectorState(rootDir);
     // First sweep: add all functions
@@ -238,7 +245,15 @@ export const inspect = async (logger, routeFiles, options = {}) => {
     // Load addon function metadata so wirings can reference addon functions
     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/dist/types.d.ts

@@ -220,6 +220,13 @@ export type InspectorOptions = Partial<{
         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;
@@ -227,6 +234,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 {
     info: (message: string) => void;
@@ -436,6 +449,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/dist/utils/extract-function-name.js

@@ -1,6 +1,23 @@
 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, rootDir) {
+    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 function makeContextBasedId(wiringType, ...segments) {
     return [wiringType, ...segments].join(':');
 }
@@ -88,7 +105,7 @@ export function extractFunctionName(callExpr, checker, rootDir) {
                                 result.pikkuFuncId = decl.name.text;
                             }
                             if (!result.pikkuFuncId) {
-                                result.pikkuFuncId = `__temp_${randomUUID()}`;
+                                result.pikkuFuncId = tempFuncId(callExpr, rootDir);
                             }
                             populateNameByPriority(result);
                             return result;
@@ -335,7 +352,7 @@ export function extractFunctionName(callExpr, checker, rootDir) {
         result.pikkuFuncId = result.exportedName;
     }
     else {
-        result.pikkuFuncId = `__temp_${randomUUID()}`;
+        result.pikkuFuncId = tempFuncId(callExpr, rootDir);
     }
     if (result.version !== null) {
         // Strip trailing VN suffix if it matches the version (e.g. createCardV1 + version:1 → createCard@v1)

package/dist/utils/schema-generator.d.ts

@@ -6,4 +6,5 @@ export declare function generateAllSchemas(logger: InspectorLogger, config: {
     schema?: {
         additionalProperties?: boolean;
     };
+    cacheDir?: string;
 }, state: InspectorState): Promise<Record<string, JSONValue>>;

package/dist/utils/schema-generator.js

@@ -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';
@@ -55,6 +57,61 @@ let cachedParsedConfig;
 let cachedTsconfigPath;
 let cachedCustomTypesContent;
 let cachedTSSchemas;
+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 = (() => {
+    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, config) {
+    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) {
+    return join(cacheDir, 'ts-schemas.json');
+}
+function readDiskTSSchemas(logger, cacheDir, key) {
+    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.message}`);
+    }
+    return null;
+}
+function writeDiskTSSchemas(logger, cacheDir, key, schemas) {
+    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.message}`);
+    }
+}
 function createProgramWithVirtualFile(tsconfig, virtualFilePath, virtualFileContent) {
     const configPath = resolve(tsconfig);
     // Cache the parsed tsconfig — it doesn't change between runs
@@ -330,12 +387,31 @@ export async function generateAllSchemas(logger, config, state) {
     const zodSchemas = await generateZodSchemas(logger, state.schemaLookup, state.functions.typesMap);
     const requiredTypes = new Set();
     const customTypesContent = generateCustomTypes(state.functions.typesMap, 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, customTypesContent, state.functions.typesMap, state.functions.meta, state.http.meta, config.schemasFromTypes, config.schema?.additionalProperties, zodSchemas);
     cachedCustomTypesContent = customTypesContent;
     cachedTSSchemas = tsSchemas;
+    if (config.cacheDir && cacheKey) {
+        writeDiskTSSchemas(logger, config.cacheDir, cacheKey, tsSchemas);
+    }
     return { ...tsSchemas, ...zodSchemas };
 }

package/dist/utils/workflow/derive-workflow-plan.d.ts

@@ -0,0 +1,20 @@
+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 declare function deriveWorkflowPlan(steps: WorkflowStepMeta[]): {
+    deterministic: boolean;
+    plannedSteps?: WorkflowPlannedStep[];
+};

package/dist/utils/workflow/derive-workflow-plan.js

@@ -0,0 +1,78 @@
+/**
+ * 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) {
+    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) {
+    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) {
+    return steps.some((step) => step.type === 'branch' || step.type === 'switch');
+}
+/** Flatten named steps (rpc/inline/sleep/parallel children) in source order. */
+function collectNamedSteps(steps) {
+    const planned = [];
+    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/dist/utils/workflow/graph/finalize-workflows.js

@@ -1,6 +1,7 @@
 import { isVersionedId, formatVersionedId, parseVersionedId } from '@pikku/core';
 import { canonicalJSON, hashString } from '../../hash.js';
 import { convertDslToGraph } from './convert-dsl-to-graph.js';
+import { deriveWorkflowPlan } from '../derive-workflow-plan.js';
 export function finalizeWorkflows(state) {
     const { workflows, functions } = state;
     const functionsMeta = functions.meta;
@@ -9,6 +10,20 @@ export function finalizeWorkflows(state) {
         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;
     }
     for (const graph of Object.values(workflows.graphMeta)) {

package/dist/utils/workflow/graph/workflow-graph.types.d.ts

@@ -69,7 +69,7 @@ export interface NodeOptions {
  * Flow node types for control flow (no RPC call)
  */
 export type FlowType = 'sleep' | 'branch' | 'parallel' | 'fanout' | 'inline' | 'switch' | 'filter' | 'arrayPredicate' | 'return' | 'cancel' | 'set';
-import type { ContextVariable, WorkflowContext } from '@pikku/core/workflow';
+import type { ContextVariable, WorkflowContext, WorkflowPlannedStep } from '@pikku/core/workflow';
 export type { ContextVariable, WorkflowContext };
 /**
  * Base node properties shared by all node types
@@ -151,6 +151,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/dist/visit.d.ts

@@ -1,4 +1,5 @@
 import * as ts from 'typescript';
 import type { InspectorState, InspectorLogger, InspectorOptions } from './types.js';
 export declare const visitSetup: (logger: InspectorLogger, checker: ts.TypeChecker, node: ts.Node, state: InspectorState, options: InspectorOptions) => void;
+export declare const visitFunctions: (logger: InspectorLogger, checker: ts.TypeChecker, node: ts.Node, state: InspectorState, options: InspectorOptions) => void;
 export declare const visitRoutes: (logger: InspectorLogger, checker: ts.TypeChecker, node: ts.Node, state: InspectorState, options: InspectorOptions) => void;

package/dist/visit.js

@@ -41,12 +41,25 @@ export const visitSetup = (logger, checker, node, state, options) => {
     addWorkflow(logger, node, checker, state, options);
     ts.forEachChild(node, (child) => visitSetup(logger, checker, child, state, options));
 };
+// 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, checker, node, state, options) => {
+    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, checker, node, state, options) => {
     const nextOptions = ts.isSourceFile(node)
         ? { ...options, sourceFile: node }
         : options;
     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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/inspector",
-  "version": "0.12.25",
+  "version": "0.12.27",
   "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.37",
+    "@pikku/core": "^0.12.39",
     "openapi-types": "^12.1.3",
     "path-to-regexp": "^8.3.0",
     "ts-json-schema-generator": "^2.5.0",

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

@@ -616,4 +616,54 @@ describe('addAuth inspector', () => {
       await rm(rootDir, { recursive: true, force: true })
     }
   })
+
+  test('user-registered global betterAuthSession sets hasUserSessionMiddleware', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-add-auth-session-'))
+    const file = join(rootDir, 'middleware.ts')
+    await writeFile(
+      file,
+      [
+        "import { addHTTPMiddleware } from '#pikku'",
+        "import { betterAuthSession } from '@pikku/better-auth'",
+        "addHTTPMiddleware('*', [",
+        '  betterAuthSession({',
+        '    impersonation: { loadUser: (id: string) => ({ id }) },',
+        '  }),',
+        '])',
+      ].join('\n')
+    )
+    const criticals: Array<{ code: ErrorCode; message: string }> = []
+    try {
+      const state = await inspect(makeLogger(criticals), [file], { rootDir })
+      assert.equal(state.auth.hasUserSessionMiddleware, true)
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+
+  test('betterAuthSession in a .gen.ts file does NOT set hasUserSessionMiddleware', async () => {
+    // Critical: the CLI's own auth.gen.ts contains addHTTPMiddleware('*',
+    // [betterAuthSession()]). It must not count as a user registration, or it
+    // would suppress itself and leave the chain with no session middleware.
+    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-add-auth-session-gen-'))
+    const file = join(rootDir, 'auth.gen.ts')
+    await writeFile(
+      file,
+      [
+        "import { addHTTPMiddleware } from '#pikku'",
+        "import { betterAuthSession } from '@pikku/better-auth'",
+        "addHTTPMiddleware('*', [betterAuthSession()])",
+      ].join('\n')
+    )
+    const criticals: Array<{ code: ErrorCode; message: string }> = []
+    try {
+      const state = await inspect(makeLogger(criticals), [file], { rootDir })
+      assert.ok(
+        !state.auth.hasUserSessionMiddleware,
+        'generated file must not self-trigger the skip'
+      )
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
 })