@pikku/inspector 0.12.47 → 0.12.49

package/src/types.ts

@@ -273,6 +273,12 @@ export type InspectorOptions = Partial<{
   rootDir: string
   isAddon: boolean
   sourceFile: ts.SourceFile
+  /**
+   * The project's tsconfig, read for its path mappings only. The inspector's
+   * program needs them to resolve imports the project reaches through `paths`;
+   * unlike `schemaConfig.tsconfig` this is also needed on a setup-only run.
+   */
+  tsconfig: string
   types: Partial<{
     configFileType: string
     userSessionType: string
@@ -423,6 +429,36 @@ export interface AuthDefinition {
   services: FunctionServicesMeta
 }
 
+/** One statically resolved entry of a feature's `scenarios` array. */
+export interface InspectorFeatureEntry {
+  /** The scenario's declared export name, with any import alias followed back. */
+  scenario: string
+  /** A `{ scenario, data }` entry's literal data — gherkin's `Examples:`. */
+  data?: unknown
+}
+
+/** A `pikkuFeature` export, as far as it can be read from the source. */
+export interface InspectorFeature {
+  path: string
+  exportedName: string
+  name?: string
+  description?: string
+  tags?: string[]
+  entries: InspectorFeatureEntry[]
+  /**
+   * Entries that are not literal — a spread, a `.map()`, a call. Counted rather
+   * than dropped so the console can say the listing is partial instead of
+   * quietly showing a short feature.
+   */
+  unresolvedEntries: number
+  /**
+   * Feature hooks run once around the whole group, never per scenario, and are
+   * runtime-only — so only their presence is recorded.
+   */
+  hasBefore: boolean
+  hasAfter: boolean
+}
+
 export interface InspectorState {
   rootDir: string // Root directory inferred from source files
   singletonServicesTypeImportMap: PathToNameAndType
@@ -466,6 +502,15 @@ export interface InspectorState {
     files: Map<string, { path: string; exportedName: string }>
     graphMeta: SerializedWorkflowGraphs
     graphFiles: Map<string, { path: string; exportedName: string }>
+    /**
+     * `pikkuFeature` exports, keyed by export identifier.
+     *
+     * Everything the config states literally is extracted here, because a
+     * feature is the document structure the console renders. Entries built by
+     * an ordinary loop cannot be enumerated statically — those are counted in
+     * `unresolvedEntries` and resolved at runtime by object identity instead.
+     */
+    featureFiles: Map<string, InspectorFeature>
     invokedWorkflows: Set<string>
   }
   rpc: {

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

@@ -45,6 +45,40 @@ export function funcIdToTypeName(id: string): string {
     .join('')
 }
 
+/**
+ * `pikkuScenarioStep({ name })` is the one wrapper whose `name` is its identity:
+ * scenarios reference a step by that string, so it must become the pikkuFuncId
+ * (and hence the generated step map's key), not just a cosmetic label the way
+ * `pikkuMiddleware`/`pikkuAgent` use it.
+ */
+function extractScenarioStepName(
+  callExpr: ts.Node,
+  result: ExtractedFunctionName
+): void {
+  if (
+    !ts.isCallExpression(callExpr) ||
+    !ts.isIdentifier(callExpr.expression) ||
+    callExpr.expression.text !== 'pikkuScenarioStep'
+  ) {
+    return
+  }
+  const firstArg = callExpr.arguments[0]
+  if (!firstArg || !ts.isObjectLiteralExpression(firstArg)) {
+    return
+  }
+  for (const prop of firstArg.properties) {
+    if (
+      ts.isPropertyAssignment(prop) &&
+      ts.isIdentifier(prop.name) &&
+      prop.name.text === 'name' &&
+      ts.isStringLiteral(prop.initializer)
+    ) {
+      result.explicitName = prop.initializer.text
+      return
+    }
+  }
+}
+
 export function extractFunctionName(
   callExpr: ts.Node,
   checker: ts.TypeChecker,
@@ -63,6 +97,8 @@ export function extractFunctionName(
     version: null,
   }
 
+  extractScenarioStepName(callExpr, result)
+
   const workflowHelpers = new Set([
     'workflow',
     'workflowStart',

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

@@ -16,6 +16,8 @@ import { extractTypeKeys } from './type-utils.js'
 import { ErrorCode } from '../error-codes.js'
 import { AUTH_HANDLER_FUNC_ID } from '../add/add-auth.js'
 import { flattenScopeDefinitions } from '@pikku/core/scope'
+import type { WorkflowStepMeta } from '@pikku/core/workflow'
+import { DYNAMIC_SCENARIO_STEP_TARGET } from './workflow/dsl/patterns.js'
 
 /**
  * Stamp the inspected authorize/callbacks service set onto the generated auth
@@ -260,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
@@ -696,6 +704,101 @@ export function validateAgentModels(
   }
 }
 
+/**
+ * Scenarios are pure stories of remote RPCs (same rule as client-side CLI
+ * renderers): the func may only destructure logger/config — everything else
+ * must go through actor steps so the flow runs against the TARGET
+ * environment, never local services.
+ *
+ * This runs in post-processing rather than in `addWorkflow` because
+ * `addWorkflow` runs in the `visitSetup` pass, which completes before
+ * `addFunctions` (`visitFunctions`) has populated `state.functions.meta` — so
+ * the check read `undefined` there and never fired.
+ */
+export function validateScenarioServices(
+  logger: InspectorLogger,
+  state: InspectorState | Omit<InspectorState, 'typesLookup'>
+): void {
+  for (const [workflowName, meta] of Object.entries(state.workflows.meta)) {
+    if (!meta.scenario) continue
+    const funcMeta = state.functions.meta[meta.pikkuFuncId]
+    if (!funcMeta?.services) continue
+    const disallowed = funcMeta.services.services.filter(
+      (svc) => svc !== 'logger' && svc !== 'config'
+    )
+    if (disallowed.length > 0) {
+      logger.critical(
+        ErrorCode.SCENARIO_HAS_SERVICES,
+        `Scenario '${workflowName}' destructures services: ${disallowed.join(', ')}. ` +
+          `Scenarios may only use 'logger'/'config' — drive everything else through ` +
+          `actor steps (workflow.do(step, rpc, data, { actor: actors.x })) so the flow ` +
+          `runs against the target environment.`
+      )
+    }
+  }
+}
+
+/**
+ * Walk every scenario step, wherever it is nested, and validate the two things
+ * that can only be known once both the workflow meta and the function meta
+ * exist:
+ *
+ * - the step target must be a static string literal (PKU678) — otherwise it
+ *   can't be bundled, typed or drawn;
+ * - a `browser: true` step must be given an actor (PKU677), since the browser
+ *   context signs in as that persona.
+ *
+ * It also marks the step's function as used, so `scenario run` boots the
+ * singletons the step actually needs.
+ */
+export function validateScenarioSteps(
+  logger: InspectorLogger,
+  state: InspectorState | Omit<InspectorState, 'typesLookup'>
+): void {
+  const visit = (workflowName: string, steps: WorkflowStepMeta[]): void => {
+    for (const step of steps) {
+      if (step.type === 'scenarioStep') {
+        if (step.stepFunc === DYNAMIC_SCENARIO_STEP_TARGET) {
+          logger.critical(
+            ErrorCode.SCENARIO_STEP_TARGET_NOT_STATIC,
+            `Scenario '${workflowName}' calls step '${step.stepName}' with a target that isn't a string literal. ` +
+              `A step target must be statically resolvable so it can be bundled, typed and drawn — ` +
+              `loop over data sets instead of computing the step name.`
+          )
+          continue
+        }
+        state.serviceAggregation.usedFunctions.add(step.stepFunc)
+        const stepMeta = state.functions.meta[step.stepFunc]
+        if (stepMeta?.scenarioStepBrowser && !step.actor) {
+          logger.critical(
+            ErrorCode.SCENARIO_BROWSER_STEP_NEEDS_ACTOR,
+            `Scenario '${workflowName}' calls browser step '${step.stepFunc}' without an actor. ` +
+              `Pass { actor: actors.<name> } so the browser context signs in as that persona.`
+          )
+        }
+        continue
+      }
+      if (step.type === 'branch') {
+        for (const branch of step.branches) visit(workflowName, branch.steps)
+        if (step.elseSteps) visit(workflowName, step.elseSteps)
+      } else if (step.type === 'switch') {
+        for (const c of step.cases ?? []) {
+          if (c.steps) visit(workflowName, c.steps)
+        }
+        if (step.defaultSteps) visit(workflowName, step.defaultSteps)
+      } else if (step.type === 'fanout' && step.body) {
+        visit(workflowName, step.body as WorkflowStepMeta[])
+      } else if (step.type === 'parallel' && step.children) {
+        visit(workflowName, step.children as WorkflowStepMeta[])
+      }
+    }
+  }
+
+  for (const [workflowName, meta] of Object.entries(state.workflows.meta)) {
+    visit(workflowName, meta.steps ?? [])
+  }
+}
+
 /**
  * A `pikkuWorkflowGraph` node that references the `graph:` namespace (e.g.
  * `graph:editFields`) needs @pikku/addon-graph wired — otherwise the RPC never

package/src/utils/serialize-inspector-state.ts

@@ -1,5 +1,9 @@
 import type { JSONValue } from '@pikku/core'
-import type { InspectorDiagnostic, InspectorState } from '../types.js'
+import type {
+  InspectorDiagnostic,
+  InspectorFeature,
+  InspectorState,
+} from '../types.js'
 import { TypesMap } from '../types-map.js'
 
 /**
@@ -139,6 +143,7 @@ export interface SerializableInspectorState {
     files: Array<[string, { path: string; exportedName: string }]>
     graphMeta: InspectorState['workflows']['graphMeta']
     graphFiles: Array<[string, { path: string; exportedName: string }]>
+    featureFiles: Array<[string, InspectorFeature]>
     invokedWorkflows: string[]
   }
   rpc: {
@@ -362,6 +367,7 @@ export function serializeInspectorState(
       files: Array.from(state.workflows.files.entries()),
       graphMeta: state.workflows.graphMeta,
       graphFiles: Array.from(state.workflows.graphFiles.entries()),
+      featureFiles: Array.from(state.workflows.featureFiles.entries()),
       invokedWorkflows: Array.from(state.workflows.invokedWorkflows),
     },
     rpc: {
@@ -558,6 +564,7 @@ export function deserializeInspectorState(
       files: new Map(data.workflows.files),
       graphMeta: data.workflows.graphMeta || {},
       graphFiles: new Map(data.workflows.graphFiles || []),
+      featureFiles: new Map(data.workflows.featureFiles || []),
       invokedWorkflows: new Set(data.workflows.invokedWorkflows || []),
     },
     rpc: {