@pikku/inspector 0.12.26 → 0.12.28

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

@@ -87,8 +87,6 @@ export interface NodeOptions {
   retryDelay?: string
   /** Timeout for node execution (e.g., '30s', '5m') */
   timeout?: string
-  /** If true, execute via queue (async). Default: false (inline) */
-  async?: boolean
 }
 
 /**
@@ -108,7 +106,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 +204,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)