@pikku/inspector 0.12.48 → 0.12.50

package/src/add/add-functions.ts

@@ -21,6 +21,7 @@ import { resolvePermissions } from '../utils/permissions.js'
 import { extractWireNames } from '../utils/post-process.js'
 import { ErrorCode } from '../error-codes.js'
 import { findPiiPaths } from '../utils/check-pii-output.js'
+import { isScenarioInstrumentationFunction } from './scenario-instrumentation.js'
 import type { NodeType } from '@pikku/core/node'
 
 const isValidVariableName = (name: string) => {
@@ -402,6 +403,11 @@ export const addFunctions: AddWiring = (
   // network would put a test harness on the public API surface.
   const isScenarioStep = expression.text === 'pikkuScenarioStep'
 
+  // A scenario's own body. Marked so the codegen partitions and the deploy
+  // analyzer can tell it apart from an application workflow without having to
+  // reach into the workflow graph.
+  const isScenario = expression.text === 'pikkuScenario'
+
   // only handle calls like pikkuFunc(...)
   if (!ts.isIdentifier(expression) || !expression.text.startsWith('pikku')) {
     return
@@ -419,6 +425,17 @@ export const addFunctions: AddWiring = (
     return
   }
 
+  // pikku's own scenario instrumentation, which older projects still carry as a
+  // scaffolded file in their source. It is not application code and must not be
+  // registered, metadata'd or deployed as if it were — `pikku dev` registers the
+  // implementations itself, and that is the only server that should have them.
+  if (
+    isScenarioInstrumentationFunction(pikkuFuncId) ||
+    isScenarioInstrumentationFunction(name)
+  ) {
+    return
+  }
+
   let title: string | undefined
   let tags: string[] | undefined
   let summary: string | undefined
@@ -1094,6 +1111,7 @@ export const addFunctions: AddWiring = (
     expose: expose || undefined,
     remote: remote || undefined,
     scenarioStep: isScenarioStep || undefined,
+    scenario: isScenario || undefined,
     mcp: mcpEnabled || undefined,
     readonly: readonly_ || undefined,
     deploy: deploy || undefined,

package/src/add/scenario-instrumentation.test.ts

@@ -0,0 +1,89 @@
+import { strict as assert } from 'assert'
+import { describe, test } from 'node:test'
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { inspect } from '../inspector.js'
+import type { InspectorLogger } from '../types.js'
+import {
+  SCENARIO_INSTRUMENTATION_FUNCTIONS,
+  isScenarioInstrumentationFunction,
+} from './scenario-instrumentation.js'
+
+const silentLogger: InspectorLogger = {
+  debug: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+  diagnostic: () => {},
+  critical: () => {},
+  hasCriticalErrors: () => false,
+}
+
+describe('scenario instrumentation', () => {
+  test('recognises the instrumentation names, including versioned ids', () => {
+    for (const name of SCENARIO_INSTRUMENTATION_FUNCTIONS) {
+      assert.ok(isScenarioInstrumentationFunction(name), name)
+      assert.ok(isScenarioInstrumentationFunction(`${name}@v2`), `${name}@v2`)
+    }
+    assert.ok(!isScenarioInstrumentationFunction('createUser'))
+    assert.ok(!isScenarioInstrumentationFunction(undefined))
+  })
+
+  test('a project still carrying the retired scaffold registers none of it', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-scenario-instr-'))
+    const file = join(rootDir, 'scenarios.gen.ts')
+
+    // What `scaffold.scenarios` used to write into the project. Whatever a
+    // project has checked in, none of it may reach the app's meta or RPC surface:
+    // `pikku dev` registers the real implementations itself.
+    await writeFile(
+      file,
+      [
+        "import { pikkuFunc } from '@pikku/core'",
+        'export const pikkuScenarioTakeLiveCoverage = pikkuFunc({',
+        "  tags: ['pikku'],",
+        '  expose: true,',
+        '  auth: true,',
+        '  func: async () => null,',
+        '})',
+        'export const pikkuScenarioResetStubs = pikkuFunc({',
+        "  tags: ['pikku'],",
+        '  expose: true,',
+        '  auth: true,',
+        '  func: async () => ({ enabled: true }),',
+        '})',
+        'export const createUser = pikkuFunc({',
+        '  expose: true,',
+        '  func: async () => ({ ok: true }),',
+        '})',
+      ].join('\n')
+    )
+
+    try {
+      const state = await inspect(silentLogger, [file], { rootDir })
+
+      for (const name of SCENARIO_INSTRUMENTATION_FUNCTIONS) {
+        assert.ok(
+          !(name in state.functions.meta),
+          `${name} must not be in the app function meta`
+        )
+        assert.ok(
+          !(name in state.rpc.internalMeta),
+          `${name} must not be in the internal RPC meta`
+        )
+        assert.ok(
+          !(name in state.rpc.exposedMeta),
+          `${name} must not be exposed`
+        )
+      }
+
+      // The application function in the same file is untouched — the drop is by
+      // name, not by file.
+      assert.ok(state.functions.meta['createUser'])
+      assert.strictEqual(state.rpc.exposedMeta['createUser'], 'createUser')
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+})

package/src/add/scenario-instrumentation.ts

@@ -0,0 +1,36 @@
+/**
+ * The instrumentation RPCs `pikku scenario run` calls on the server it is
+ * testing: snapshot/reset live coverage, and reset/read recorded stub calls.
+ *
+ * They are pikku's own, not the application's. They used to be scaffolded into
+ * the project as ordinary `pikkuFunc`s, which made them indistinguishable from
+ * application code — so they were registered in the app bootstrap, listed in the
+ * app's function and RPC meta, and shipped, `expose: true`, in every deployed
+ * bundle. A deployment has no use for them: coverage and stub inspection are
+ * things you do to a development server.
+ *
+ * The inspector therefore ignores these names wherever it finds them, and
+ * `pikku dev` registers the implementations itself. Ignoring by name (rather
+ * than deleting the scaffold and requiring every project to regenerate) is what
+ * keeps an existing project's checked-in `scenarios.gen.ts` from deploying.
+ */
+export const SCENARIO_INSTRUMENTATION_FUNCTIONS = [
+  'pikkuScenarioTakeLiveCoverage',
+  'pikkuScenarioResetLiveCoverage',
+  'pikkuScenarioResetStubs',
+  'pikkuScenarioGetStubCalls',
+] as const
+
+export type ScenarioInstrumentationFunction =
+  (typeof SCENARIO_INSTRUMENTATION_FUNCTIONS)[number]
+
+const names = new Set<string>(SCENARIO_INSTRUMENTATION_FUNCTIONS)
+
+/**
+ * True for a scenario instrumentation function, by name. Versioned ids
+ * (`name@v2`) are matched on their base so a project that bumps one is still
+ * covered.
+ */
+export const isScenarioInstrumentationFunction = (
+  name: string | undefined
+): boolean => (name ? names.has(name.split('@')[0]!) : false)

package/src/add/scenario-marker.test.ts

@@ -0,0 +1,89 @@
+/**
+ * The `scenario` / `scenarioStep` markers in the *function* meta are what every
+ * deployment boundary downstream reads: the codegen partition, the RPC meta
+ * filter, the schema split and the deploy analyzer. Asserting them on a real
+ * `pikkuScenario(...)` is what makes those filters mean anything — filters tested
+ * against hand-written meta would keep passing if extraction stopped setting it.
+ */
+import { strict as assert } from 'assert'
+import { describe, test } from 'node:test'
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { inspect } from '../inspector.js'
+import type { InspectorLogger } from '../types.js'
+
+const logger = {
+  debug: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+  diagnostic: () => {},
+  critical: () => {},
+  hasCriticalErrors: () => false,
+} as unknown as InspectorLogger
+
+const STEPS = [
+  "import { pikkuScenarioStep } from '@pikku/core'",
+  'export const buysAnApple = pikkuScenarioStep({',
+  "  name: 'buysAnApple',",
+  "  description: 'buys an apple',",
+  '  func: async ({ logger }, data: { qty: number }) => ({ ok: data.qty > 0 }),',
+  '})',
+].join('\n')
+
+const APP = [
+  "import { pikkuFunc } from '@pikku/core'",
+  'export const createTodo = pikkuFunc({',
+  '  expose: true,',
+  '  func: async (_services, data: { title: string }) => ({ id: data.title }),',
+  '})',
+].join('\n')
+
+const SCENARIO = [
+  "import { pikkuScenario } from '@pikku/core/workflow'",
+  'export const shopFlow = pikkuScenario({',
+  "  title: 'Buys an apple',",
+  '  func: async (_services, _input, { scenario }: any) => {',
+  "    await scenario.when('buys an apple', 'buysAnApple', { qty: 1 })",
+  '    return { ok: true }',
+  '  },',
+  '})',
+].join('\n')
+
+describe('scenario markers in the function meta', () => {
+  test('a real pikkuScenario and pikkuScenarioStep are marked, an application function is not', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-scenario-marker-'))
+    const files = [
+      [join(rootDir, 'shop.steps.ts'), STEPS],
+      [join(rootDir, 'shop.scenario.ts'), SCENARIO],
+      [join(rootDir, 'todo.function.ts'), APP],
+    ] as const
+    await Promise.all(files.map(([path, source]) => writeFile(path, source)))
+
+    try {
+      const state = await inspect(
+        logger,
+        files.map(([path]) => path),
+        { rootDir }
+      )
+
+      const scenario = state.functions.meta['shopFlow']
+      assert.ok(scenario, 'the scenario body is a function and must have meta')
+      assert.equal(scenario.scenario, true)
+      assert.equal(scenario.scenarioStep, undefined)
+
+      const step = state.functions.meta['buysAnApple']
+      assert.ok(step)
+      assert.equal(step.scenarioStep, true)
+      assert.equal(step.scenario, undefined)
+
+      const app = state.functions.meta['createTodo']
+      assert.ok(app)
+      assert.equal(app.scenario, undefined)
+      assert.equal(app.scenarioStep, undefined)
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+})

package/src/index.ts

@@ -5,6 +5,11 @@ export type { FilesAndMethodsErrors } from './utils/get-files-and-methods.js'
 export { ErrorCode } from './error-codes.js'
 export type { DiagnosticSeverity, CodedDiagnostic } from './error-codes.js'
 export { AUTH_HANDLER_FUNC_ID } from './add/add-auth.js'
+export {
+  SCENARIO_INSTRUMENTATION_FUNCTIONS,
+  isScenarioInstrumentationFunction,
+} from './add/scenario-instrumentation.js'
+export type { ScenarioInstrumentationFunction } from './add/scenario-instrumentation.js'
 export {
   serializeInspectorState,
   deserializeInspectorState,

package/src/utils/post-process.test.ts

@@ -64,6 +64,7 @@ function makeState(
     addonFunctions?: Record<string, Record<string, any>>
     addonRequiredParentServices?: string[]
     authServices?: string[]
+    graphMeta?: Record<string, any>
   } = {}
 ): Omit<InspectorState, 'typesLookup'> {
   return {
@@ -95,7 +96,7 @@ function makeState(
     scheduledTasks: { meta: {} },
     mcpEndpoints: { toolsMeta: {}, promptsMeta: {}, resourcesMeta: {} },
     agents: { agentsMeta: {} },
-    workflows: { meta: {}, graphMeta: {} },
+    workflows: { meta: {}, graphMeta: overrides.graphMeta ?? {} },
     wireServicesMeta: new Map(),
     rpc: { internalMeta: {}, exposedMeta: {} },
     addonFunctions: overrides.addonFunctions ?? {},
@@ -117,6 +118,34 @@ const CONSOLE_PARENT_SERVICES = [
   'credentialService',
 ]
 
+describe('aggregateRequiredServices — synthetic workflow queue workers', () => {
+  const graphMeta = {
+    orderWorkflow: {
+      name: 'orderWorkflow',
+      source: 'dsl',
+      nodes: { 'step-1': { rpcName: 'chargeCard' } },
+    },
+    loginScenario: {
+      name: 'loginScenario',
+      source: 'scenario',
+      nodes: { 'step-1': { rpcName: 'opensPage' } },
+    },
+  }
+
+  // A scenario IS a workflow, so it used to be handed an orchestrator queue
+  // worker in the app's queue meta — which the app bootstrap registers and every
+  // deployed bundle therefore carries, leaving a provider to create a production
+  // queue named after a test. Nothing dispatches a scenario through a queue:
+  // `pikku scenario run` executes its steps in-process.
+  test('a scenario gets no orchestrator queue worker', () => {
+    const state = makeState({ graphMeta })
+    aggregateRequiredServices(state)
+    assert.deepEqual(Object.keys(state.queueWorkers.meta), [
+      'wf-orchestrator-order-workflow',
+    ])
+  })
+})
+
 describe('aggregateRequiredServices — per-function addon services', () => {
   test('a used addon function adds only its own parent services', () => {
     const state = makeState({

package/src/utils/post-process.ts

@@ -262,6 +262,12 @@ export function aggregateRequiredServices(
   // per-workflow queue entries and falls back to shared queue names.
   for (const [, graph] of Object.entries(state.workflows.graphMeta)) {
     if (!graph.nodes || !graph.name) continue
+    // A scenario is a workflow, but it only ever runs in-process under
+    // `pikku scenario run` — no step of one is dispatched through a queue. The
+    // synthetic entries were pure leakage: they put a
+    // `wf-orchestrator-<scenario>` worker into the app's queue meta, which every
+    // bundle imports and a provider then creates as a real production queue.
+    if (graph.source === 'scenario') continue
 
     const toKebab = (s: string) =>
       s

package/src/utils/schema-cache.test.ts

@@ -0,0 +1,124 @@
+import { test, describe } from 'node:test'
+import { strict as assert } from 'node:assert'
+import {
+  mkdtempSync,
+  rmSync,
+  statSync,
+  utimesSync,
+  writeFileSync,
+} from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import {
+  readDiskTSSchemas,
+  writeDiskTSSchemas,
+  type SchemaDep,
+} from './schema-generator.js'
+import type { InspectorLogger } from '../types.js'
+
+const silentLogger = {
+  debug: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+} as unknown as InspectorLogger
+
+const KEY = 'test-key'
+const SCHEMAS = { Thing: { type: 'object' } }
+
+/** A cache directory and one source file the cached schemas claim to derive from. */
+function makeCache(sourceContent: string): {
+  cacheDir: string
+  source: string
+  deps: SchemaDep[]
+  cleanup: () => void
+} {
+  const dir = mkdtempSync(join(tmpdir(), 'pikku-schema-cache-'))
+  const source = join(dir, 'thing.ts')
+  writeFileSync(source, sourceContent)
+  const stat = statSync(source)
+  return {
+    cacheDir: dir,
+    source,
+    deps: [{ path: source, mtimeMs: stat.mtimeMs, size: stat.size }],
+    cleanup: () => rmSync(dir, { recursive: true, force: true }),
+  }
+}
+
+describe('TS schema disk cache', () => {
+  test('serves the cached schemas while their sources are untouched', () => {
+    const { cacheDir, deps, cleanup } = makeCache('export interface Thing {}')
+    try {
+      writeDiskTSSchemas(silentLogger, cacheDir, KEY, SCHEMAS, deps)
+      const hit = readDiskTSSchemas(silentLogger, cacheDir, KEY)
+      assert.deepEqual(hit?.schemas, SCHEMAS)
+    } finally {
+      cleanup()
+    }
+  })
+
+  test('discards the cache when a type it was built from changes', () => {
+    const { cacheDir, source, deps, cleanup } = makeCache(
+      'export interface Thing {}'
+    )
+    try {
+      writeDiskTSSchemas(silentLogger, cacheDir, KEY, SCHEMAS, deps)
+      // The shape changes but the name does not, so the cache key — which hashes
+      // only the synthesized custom-types source — is identical. This is the case
+      // that used to serve a stale schema, and it survived `rm -rf .pikku`
+      // because the cache lives under node_modules/.cache.
+      writeFileSync(source, 'export interface Thing { added: string }')
+      assert.equal(readDiskTSSchemas(silentLogger, cacheDir, KEY), null)
+    } finally {
+      cleanup()
+    }
+  })
+
+  test('discards the cache when a source is rewritten to the same size', () => {
+    const { cacheDir, source, deps, cleanup } = makeCache('export type A = 1')
+    try {
+      writeDiskTSSchemas(silentLogger, cacheDir, KEY, SCHEMAS, deps)
+      // Same byte count, different type: size alone would call this unchanged, so
+      // the mtime half of the fingerprint is what has to catch it.
+      writeFileSync(source, 'export type A = 2')
+      utimesSync(source, new Date(), new Date(Date.now() + 5000))
+      assert.equal(readDiskTSSchemas(silentLogger, cacheDir, KEY), null)
+    } finally {
+      cleanup()
+    }
+  })
+
+  test('discards the cache when a source it was built from is deleted', () => {
+    const { cacheDir, source, deps, cleanup } = makeCache('export type A = 1')
+    try {
+      writeDiskTSSchemas(silentLogger, cacheDir, KEY, SCHEMAS, deps)
+      rmSync(source)
+      assert.equal(readDiskTSSchemas(silentLogger, cacheDir, KEY), null)
+    } finally {
+      cleanup()
+    }
+  })
+
+  test('discards a cache written before deps were tracked', () => {
+    const { cacheDir, cleanup } = makeCache('export type A = 1')
+    try {
+      writeFileSync(
+        join(cacheDir, 'ts-schemas.json'),
+        JSON.stringify({ key: KEY, schemas: SCHEMAS })
+      )
+      assert.equal(readDiskTSSchemas(silentLogger, cacheDir, KEY), null)
+    } finally {
+      cleanup()
+    }
+  })
+
+  test('still misses on a different key', () => {
+    const { cacheDir, deps, cleanup } = makeCache('export type A = 1')
+    try {
+      writeDiskTSSchemas(silentLogger, cacheDir, KEY, SCHEMAS, deps)
+      assert.equal(readDiskTSSchemas(silentLogger, cacheDir, 'other'), null)
+    } finally {
+      cleanup()
+    }
+  })
+})

package/src/utils/schema-generator.test.ts

@@ -5,7 +5,7 @@ import { tmpdir } from 'os'
 import { join } from 'path'
 
 import { getInitialInspectorState } from '../inspector.js'
-import { generateAllSchemas } from './schema-generator.js'
+import { generateAllSchemas, schemaRuntimeFile } from './schema-generator.js'
 
 const debugLines: string[] = []
 const logger = {
@@ -162,3 +162,64 @@ describe('generateAllSchemas', () => {
     )
   })
 })
+
+/**
+ * A schema imported from a built workspace package resolves to that package's
+ * declaration file, and a `.d.ts` has no runtime exports at all — every one of
+ * them is a type. Importing it to read the zod object yields an empty module and
+ * every schema in it is reported missing, so the emitted JS beside it is what has
+ * to be imported.
+ */
+describe('schemaRuntimeFile', () => {
+  test('a source file the developer wrote is imported as it is', () => {
+    const written = join(projectDir, 'src', 'types.ts')
+    assert.equal(schemaRuntimeFile(written), written)
+  })
+
+  test('a declaration file resolves to the JS emitted beside it', () => {
+    writeFileSync(
+      join(projectDir, 'src', 'reindex.d.ts'),
+      'export declare const a: number\n'
+    )
+    writeFileSync(join(projectDir, 'src', 'reindex.js'), 'export const a = 1\n')
+    assert.equal(
+      schemaRuntimeFile(join(projectDir, 'src', 'reindex.d.ts')),
+      join(projectDir, 'src', 'reindex.js')
+    )
+  })
+
+  test('.d.mts resolves to the ESM file beside it', () => {
+    writeFileSync(
+      join(projectDir, 'src', 'esm.d.mts'),
+      'export declare const a: number\n'
+    )
+    writeFileSync(join(projectDir, 'src', 'esm.mjs'), 'export const a = 1\n')
+    assert.equal(
+      schemaRuntimeFile(join(projectDir, 'src', 'esm.d.mts')),
+      join(projectDir, 'src', 'esm.mjs')
+    )
+  })
+
+  test('.d.cts resolves to the CommonJS file beside it', () => {
+    // Its own test rather than a second assertion above: the two extensions are
+    // separate branches, and one covering both is one that passes while half of
+    // it is broken.
+    writeFileSync(
+      join(projectDir, 'src', 'commonjs.d.cts'),
+      'export declare const a: number\n'
+    )
+    writeFileSync(join(projectDir, 'src', 'commonjs.cjs'), 'exports.a = 1\n')
+    assert.equal(
+      schemaRuntimeFile(join(projectDir, 'src', 'commonjs.d.cts')),
+      join(projectDir, 'src', 'commonjs.cjs')
+    )
+  })
+
+  test('a declaration file with no emitted JS keeps its own path', () => {
+    // So the "could not find exported schema" error still names a file the
+    // developer can open, rather than one that was never written.
+    const orphan = join(projectDir, 'src', 'types-only.d.ts')
+    writeFileSync(orphan, 'export declare const a: number\n')
+    assert.equal(schemaRuntimeFile(orphan), orphan)
+  })
+})