@pikku/inspector 0.12.26 → 0.12.28

package/CHANGELOG.md

@@ -1,3 +1,118 @@
+## 0.12.28
+
+### Patch Changes
+
+- 66d43d1: Add `deploy.defaultTarget` to `pikku.config.json` to override the default deploy target ('serverless') for functions without an explicit `deploy` flag.
+- a8c9e6d: feat(inspector): add PKU940 — block type casts on rpc.invoke() calls
+
+  The inspector now emits a critical PKU940 error when `rpc.invoke()` is called
+  with an `as` cast on an argument (`rpc.invoke('fn', data as any)`) or when its
+  result is cast (`rpc.invoke('fn', data) as any`). Both patterns defeat Pikku's
+  generated type safety and are rejected at build time.
+
+- ba1ab08: refactor(workflow): replace `inline: false` with `workflowQueued: true` on function meta
+
+  The per-function workflow dispatch flag has been renamed from the confusing
+  negative `inline: false` to the explicit positive `workflowQueued: true`.
+  Two companion fields are also added: `workflowRetries` and `workflowTimeout`
+  as function-level equivalents of the per-call-site `NodeOptions` fields.
+
+  **Breaking change (patch — flag was undocumented):** rename `inline: false`
+  to `workflowQueued: true` on any `pikkuSessionlessFunc` / `pikkuFunc` that
+  dispatches its workflow steps via the queue.
+
+  **Behaviour change:** a step marked `workflowQueued: true` now throws if no
+  queue service is configured, instead of silently falling back to inline
+  execution.
+
+  **Bug fix:** `post-process.ts` was registering `wf-step-*` queues for every
+  workflow step node; it now only registers them for steps that are actually
+  `workflowQueued: true`, avoiding spurious queue resource allocation.
+
+- Updated dependencies [ba1ab08]
+  - @pikku/core@0.12.40
+
+## 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

package/dist/add/add-functions.js

@@ -277,7 +277,9 @@ export const addFunctions = (logger, node, checker, state, options) => {
     let deploy;
     let approvalRequired;
     let approvalDescription;
-    let inline;
+    let workflowQueued;
+    let workflowRetries;
+    let workflowTimeout;
     let version;
     let objectNode;
     let nodeDisplayName = null;
@@ -345,7 +347,9 @@ export const addFunctions = (logger, node, checker, state, options) => {
         readonly_ = getPropertyValue(firstArg, 'readonly');
         deploy = getPropertyValue(firstArg, 'deploy');
         approvalRequired = getPropertyValue(firstArg, 'approvalRequired');
-        inline = getPropertyValue(firstArg, 'inline');
+        workflowQueued = getPropertyValue(firstArg, 'workflowQueued');
+        workflowRetries = getPropertyValue(firstArg, 'workflowRetries');
+        workflowTimeout = getPropertyValue(firstArg, 'workflowTimeout');
         // Extract approvalDescription identifier reference
         for (const prop of firstArg.properties) {
             if (ts.isPropertyAssignment(prop) &&
@@ -647,7 +651,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);
@@ -735,7 +744,9 @@ export const addFunctions = (logger, node, checker, state, options) => {
         deploy: deploy || undefined,
         approvalRequired: approvalRequired || undefined,
         approvalDescription: approvalDescription || undefined,
-        inline: inline === false ? false : undefined,
+        workflowQueued: workflowQueued === true ? true : undefined,
+        workflowRetries: workflowRetries ?? undefined,
+        workflowTimeout: workflowTimeout ?? undefined,
         implementationHash,
         version,
         title,

package/dist/add/add-rpc-invocations.js

@@ -1,4 +1,18 @@
 import * as ts from 'typescript';
+import { ErrorCode } from '../error-codes.js';
+function hasTypeCast(node) {
+    return ts.isAsExpression(node) || ts.isTypeAssertionExpression(node);
+}
+function outerParent(node) {
+    let p = node.parent;
+    while (p && (ts.isAwaitExpression(p) || ts.isParenthesizedExpression(p))) {
+        p = p.parent;
+    }
+    return p;
+}
+function findCastArg(args) {
+    return args.find(hasTypeCast);
+}
 /**
  * Helper to extract namespace from a namespaced function reference like 'ext:hello'
  */
@@ -52,6 +66,19 @@ export function addRPCInvocations(node, state, logger) {
             expression.name.text === 'invoke' &&
             ts.isIdentifier(expression.expression) &&
             expression.expression.text === 'rpc') {
+            // Skip PKU940 for generated files — they may contain intentional casts
+            // (e.g. the paginated useInfiniteQuery hook in pikku-react-query.gen.ts).
+            const sourceFileName = node.getSourceFile().fileName;
+            const isGenerated = sourceFileName.endsWith('.gen.ts') || sourceFileName.endsWith('.gen.js');
+            if (!isGenerated) {
+                if (hasTypeCast(outerParent(node))) {
+                    logger.critical(ErrorCode.RPC_INVOCATION_TYPE_CAST, `rpc.invoke() result is type-cast — remove the 'as' expression and rely on Pikku's generated types`);
+                }
+                const castArg = findCastArg(args);
+                if (castArg) {
+                    logger.critical(ErrorCode.RPC_INVOCATION_TYPE_CAST, `rpc.invoke() has a type cast on an argument — remove the 'as' expression and rely on Pikku's generated types`);
+                }
+            }
             const [firstArg] = args;
             if (firstArg) {
                 if (ts.isStringLiteral(firstArg)) {

package/dist/error-codes.d.ts

@@ -59,7 +59,8 @@ export declare enum ErrorCode {
     WORKFLOW_MULTI_QUEUE_NOT_SUPPORTED = "PKU901",
     PII_IN_OUTPUT = "PKU910",
     ADDON_WIRING_NOT_ALLOWED = "PKU920",
-    ADDON_CONTRACT_HANDLERS_NOT_ALLOWED = "PKU921"
+    ADDON_CONTRACT_HANDLERS_NOT_ALLOWED = "PKU921",
+    RPC_INVOCATION_TYPE_CAST = "PKU940"
 }
 /**
  * Severity of a tracked, coded diagnostic. `critical` always blocks the build;

package/dist/error-codes.js

@@ -75,4 +75,5 @@ export var ErrorCode;
     // Addon authoring errors
     ErrorCode["ADDON_WIRING_NOT_ALLOWED"] = "PKU920";
     ErrorCode["ADDON_CONTRACT_HANDLERS_NOT_ALLOWED"] = "PKU921";
+    ErrorCode["RPC_INVOCATION_TYPE_CAST"] = "PKU940";
 })(ErrorCode || (ErrorCode = {}));

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

@@ -196,6 +196,7 @@ export type InspectorFilters = {
     target?: Array<'serverless' | 'server'>;
     excludeTarget?: Array<'serverless' | 'server'>;
     serverlessIncompatible?: string[];
+    defaultTarget?: 'serverless' | 'server';
 };
 export type AddonConfig = {
     package: string;
@@ -220,6 +221,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 +235,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;

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/filter-inspector-state.js

@@ -256,9 +256,10 @@ export function filterInspectorState(state, filters, logger) {
             ? new Set(filters.excludeTarget)
             : null;
         const incompatible = new Set(filters.serverlessIncompatible ?? []);
+        const defaultTarget = filters.defaultTarget ?? 'serverless';
         keptByDeploy = new Set();
         for (const [funcId, funcMeta] of Object.entries(state.functions.meta)) {
-            const target = resolveDeployTarget(funcMeta, incompatible, funcId);
+            const target = resolveDeployTarget(funcMeta, incompatible, funcId, defaultTarget);
             if (allowed && !allowed.has(target))
                 continue;
             if (excluded && excluded.has(target))
@@ -761,10 +762,10 @@ export function filterInspectorState(state, filters, logger) {
         filteredState.requiredSchemas = prunedSchemas;
     }
     // Step dispatch is decided purely per-function: a workflow step runs via the
-    // queue only when its function opts out of inline execution (inline: false).
-    // Such a unit needs workflowService + queueService injected even though the
-    // function itself doesn't reference them. Check the ORIGINAL graph meta
-    // (before filtering pruned it).
+    // queue only when its function is marked `workflowQueued: true`. Such a unit
+    // needs workflowService + queueService injected even though the function
+    // itself doesn't reference them. Check the ORIGINAL graph meta (before
+    // filtering pruned it).
     const survivingFuncIds = new Set(Object.keys(filteredState.functions.meta));
     const resolveFuncId = (rpcName) => filteredState.rpc.internalMeta[rpcName] ??
         filteredState.rpc.exposedMeta[rpcName] ??
@@ -782,7 +783,7 @@ export function filterInspectorState(state, filters, logger) {
                 continue;
             const funcMeta = (filteredState.functions.meta[funcId] ??
                 filteredState.functions.meta[rpcName]);
-            if (funcMeta?.inline === false) {
+            if (funcMeta?.workflowQueued === true) {
                 filteredState.serviceAggregation.requiredServices.add('workflowService');
                 filteredState.serviceAggregation.requiredServices.add('queueService');
             }

package/dist/utils/post-process.js

@@ -220,11 +220,18 @@ export function aggregateRequiredServices(state) {
                 pikkuFuncId: `pikkuWorkflowOrchestrator:${graph.name}`,
             };
         }
-        // Per-step queues
+        // Per-step queues — only for steps explicitly marked workflowQueued: true
         for (const node of Object.values(graph.nodes)) {
             if (!('rpcName' in node) || !node.rpcName)
                 continue;
             const rpcName = node.rpcName;
+            const funcId = state.rpc?.internalMeta?.[rpcName] ??
+                state.rpc?.exposedMeta?.[rpcName] ??
+                rpcName;
+            const funcMeta = (state.functions.meta[funcId] ??
+                state.functions.meta[rpcName]);
+            if (funcMeta?.workflowQueued !== true)
+                continue;
             const stepQueueName = `wf-step-${toKebab(rpcName)}`;
             if (!state.queueWorkers.meta[stepQueueName]) {
                 state.queueWorkers.meta[stepQueueName] = {

package/dist/utils/resolve-deploy-target.d.ts

@@ -18,11 +18,12 @@ export declare class IncompatibleDeployTargetError extends Error {
  *      - throw if the function explicitly declares `deploy: 'serverless'`
  *      - otherwise target is 'server'
  *   2. Explicit `funcMeta.deploy: 'serverless' | 'server'`
- *   3. Default 'serverless'
+ *   3. `defaultTarget` (sourced from `pikku.config.json` →
+ *      `deploy.defaultTarget`, falling back to 'serverless')
  *
  * Used both by the per-unit deploy analyzer (when bucketing functions
  * into deployment units) and by `filterInspectorState` (when
  * `pikku all --deploy <target>` is used to emit a target-scoped set
  * of gen files).
  */
-export declare function resolveDeployTarget(funcMeta: Pick<FunctionMeta, 'deploy' | 'services'>, serverlessIncompatible: Set<string>, functionName?: string): 'serverless' | 'server';
+export declare function resolveDeployTarget(funcMeta: Pick<FunctionMeta, 'deploy' | 'services'>, serverlessIncompatible: Set<string>, functionName?: string, defaultTarget?: 'serverless' | 'server'): 'serverless' | 'server';

package/dist/utils/resolve-deploy-target.js

@@ -25,14 +25,15 @@ export class IncompatibleDeployTargetError extends Error {
  *      - throw if the function explicitly declares `deploy: 'serverless'`
  *      - otherwise target is 'server'
  *   2. Explicit `funcMeta.deploy: 'serverless' | 'server'`
- *   3. Default 'serverless'
+ *   3. `defaultTarget` (sourced from `pikku.config.json` →
+ *      `deploy.defaultTarget`, falling back to 'serverless')
  *
  * Used both by the per-unit deploy analyzer (when bucketing functions
  * into deployment units) and by `filterInspectorState` (when
  * `pikku all --deploy <target>` is used to emit a target-scoped set
  * of gen files).
  */
-export function resolveDeployTarget(funcMeta, serverlessIncompatible, functionName = '<unknown>') {
+export function resolveDeployTarget(funcMeta, serverlessIncompatible, functionName = '<unknown>', defaultTarget = 'serverless') {
     // Service compatibility wins over the explicit flag — a serverless
     // bundle of a function that needs (e.g.) node:fs would crash at runtime.
     const incompatibleHits = [];
@@ -52,5 +53,5 @@ export function resolveDeployTarget(funcMeta, serverlessIncompatible, functionNa
         return 'server';
     if (funcMeta.deploy === 'serverless')
         return 'serverless';
-    return 'serverless';
+    return defaultTarget;
 }

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;
+}