@pikku/core 0.12.69 → 0.12.71

package/dist/wirings/workflow/graph/graph-validation.js

@@ -1,5 +1,3 @@
-import { pikkuState } from '../../../pikku-state.js';
-import { resolveNamespace } from '../../rpc/rpc-runner.js';
 function normalizeTargets(value) {
     if (!value)
         return [];
@@ -16,146 +14,6 @@ function normalizeTargets(value) {
     }
     return [];
 }
-function collectRefs(value, refs) {
-    if (typeof value === 'object' &&
-        value !== null &&
-        '$ref' in value &&
-        typeof value.$ref === 'string') {
-        refs.add(value.$ref);
-        return;
-    }
-    if (Array.isArray(value)) {
-        for (const item of value)
-            collectRefs(item, refs);
-        return;
-    }
-    if (typeof value === 'object' && value !== null) {
-        for (const v of Object.values(value))
-            collectRefs(v, refs);
-    }
-}
-function resolveToolMeta(toolName) {
-    const resolved = toolName.includes(':') ? resolveNamespace(toolName) : null;
-    if (resolved) {
-        const fnMeta = pikkuState(resolved.package, 'function', 'meta')[resolved.function];
-        const schemas = pikkuState(resolved.package, 'misc', 'schemas');
-        return fnMeta ? { fnMeta, schemas } : null;
-    }
-    const rpcMeta = pikkuState(null, 'rpc', 'meta');
-    const pikkuFuncId = rpcMeta[toolName];
-    if (!pikkuFuncId)
-        return null;
-    const fnMeta = pikkuState(null, 'function', 'meta')[pikkuFuncId];
-    const schemas = pikkuState(null, 'misc', 'schemas');
-    return fnMeta ? { fnMeta, schemas } : null;
-}
-export function computeEntryNodeIds(nodes) {
-    const referenced = new Set();
-    for (const node of Object.values(nodes)) {
-        if (node.next) {
-            for (const target of normalizeTargets(node.next)) {
-                referenced.add(target);
-            }
-        }
-        if (node.onError) {
-            for (const target of normalizeTargets(node.onError)) {
-                referenced.add(target);
-            }
-        }
-    }
-    return Object.keys(nodes).filter((id) => !referenced.has(id));
-}
-export function validateWorkflowWiring(nodes, toolNames) {
-    const errors = [];
-    const nodeIds = new Set(Object.keys(nodes));
-    const toolSet = new Set(toolNames);
-    for (const [nodeId, node] of Object.entries(nodes)) {
-        if (!node.rpcName) {
-            errors.push(`Node '${nodeId}' is missing 'rpcName'`);
-            continue;
-        }
-        if (!toolSet.has(node.rpcName)) {
-            errors.push(`Node '${nodeId}' references unknown tool '${node.rpcName}'. Available tools: ${toolNames.join(', ')}`);
-            continue;
-        }
-        const nextTargets = normalizeTargets(node.next);
-        for (const target of nextTargets) {
-            if (!nodeIds.has(target)) {
-                errors.push(`Node '${nodeId}' routes to unknown node '${target}' in 'next'`);
-            }
-        }
-        const errorTargets = normalizeTargets(node.onError);
-        for (const target of errorTargets) {
-            if (!nodeIds.has(target)) {
-                errors.push(`Node '${nodeId}' routes to unknown node '${target}' in 'onError'`);
-            }
-        }
-        if (!node.input)
-            continue;
-        const refs = new Set();
-        collectRefs(node.input, refs);
-        for (const ref of refs) {
-            if (ref === 'trigger' || ref === '$item') {
-                const targetMeta = resolveToolMeta(node.rpcName);
-                if (targetMeta?.fnMeta?.inputSchemaName) {
-                    const targetSchema = targetMeta.schemas.get(targetMeta.fnMeta.inputSchemaName);
-                    if (targetSchema?.properties) {
-                        for (const [field, fieldValue] of Object.entries(node.input)) {
-                            if (typeof fieldValue === 'object' &&
-                                fieldValue !== null &&
-                                fieldValue.$ref === ref &&
-                                !fieldValue.path) {
-                                const targetType = targetSchema.properties[field]?.type;
-                                if (targetType && targetType !== 'object') {
-                                    errors.push(`Node '${nodeId}' input field '${field}' expects type '${targetType}', but references the whole ${ref} object without a path. Use { $ref: "${ref}", path: "${field}" } to extract the field.`);
-                                }
-                            }
-                        }
-                    }
-                }
-                continue;
-            }
-            if (!nodeIds.has(ref)) {
-                errors.push(`Node '${nodeId}' references unknown node '${ref}' in input`);
-                continue;
-            }
-            const sourceNode = nodes[ref];
-            if (!sourceNode?.rpcName)
-                continue;
-            const sourceMeta = resolveToolMeta(sourceNode.rpcName);
-            if (!sourceMeta?.fnMeta?.outputSchemaName)
-                continue;
-            const sourceSchema = sourceMeta.schemas.get(sourceMeta.fnMeta.outputSchemaName);
-            if (!sourceSchema?.properties)
-                continue;
-            for (const [field, fieldValue] of Object.entries(node.input)) {
-                if (typeof fieldValue === 'object' &&
-                    fieldValue !== null &&
-                    fieldValue.$ref === ref &&
-                    fieldValue.path) {
-                    const pathRoot = fieldValue.path.split('.')[0];
-                    if (sourceSchema.properties &&
-                        !(pathRoot in sourceSchema.properties)) {
-                        errors.push(`Node '${nodeId}' input field '${field}' references path '${fieldValue.path}' but node '${ref}' (${sourceNode.rpcName}) output has no property '${pathRoot}'`);
-                        continue;
-                    }
-                    const targetMeta = resolveToolMeta(node.rpcName);
-                    if (!targetMeta?.fnMeta?.inputSchemaName)
-                        continue;
-                    const targetSchema = targetMeta.schemas.get(targetMeta.fnMeta.inputSchemaName);
-                    if (!targetSchema?.properties?.[field])
-                        continue;
-                    const sourceType = sourceSchema.properties[pathRoot]?.type;
-                    const targetType = targetSchema.properties[field].type;
-                    if (sourceType && targetType && sourceType !== targetType) {
-                        errors.push(`Node '${nodeId}' input field '${field}' expects type '${targetType}', but node '${ref}' output field '${pathRoot}' is type '${sourceType}'`);
-                    }
-                }
-            }
-        }
-    }
-    return errors;
-}
 export function generateMermaidDiagram(workflowName, nodes, entryNodeIds) {
     const lines = ['graph TD'];
     for (const [nodeId, node] of Object.entries(nodes)) {

package/dist/wirings/workflow/graph/index.d.ts

@@ -2,4 +2,4 @@ export { continueGraph, executeGraphStep, onGraphNodeComplete, runFromMeta, runW
 export { template } from './template.js';
 export type { TemplateString } from './template.js';
 export { pikkuWorkflowGraph, type PikkuWorkflowGraphConfig, type PikkuWorkflowGraphResult, } from './wire-workflow-graph.js';
-export { validateWorkflowWiring, computeEntryNodeIds, generateMermaidDiagram, } from './graph-validation.js';
+export { generateMermaidDiagram } from './graph-validation.js';

package/dist/wirings/workflow/graph/index.js

@@ -1,4 +1,4 @@
 export { continueGraph, executeGraphStep, onGraphNodeComplete, runFromMeta, runWorkflowGraph, } from './graph-runner.js';
 export { template } from './template.js';
 export { pikkuWorkflowGraph, } from './wire-workflow-graph.js';
-export { validateWorkflowWiring, computeEntryNodeIds, generateMermaidDiagram, } from './graph-validation.js';
+export { generateMermaidDiagram } from './graph-validation.js';

package/dist/wirings/workflow/index.d.ts

@@ -2,14 +2,24 @@
  * Workflow module exports
  */
 export { PikkuWorkflowService, WorkflowCancelledException, WorkflowSuspendedException, WorkflowDispatchException, WorkflowNotFoundError, WorkflowRunNotFoundError, WorkflowApprovalResolvedError, DEFAULT_STEP_RETRIES, } from './pikku-workflow-service.js';
+export type { RunLifecycleContext, WorkflowRunEngine, WorkflowRunExtension, } from './pikku-workflow-service.js';
 export { deriveInvocationId, uuidv5 } from './workflow-invocation-id.js';
 export { buildRunTimeline, reconstructStateAt, reconstructFinalState, } from './run-timeline.js';
 export type { RunTimeline, RunTimelineEvent, ReconstructedRunState, ReconstructedStep, RunPhase, } from './run-timeline.js';
 export { addWorkflow } from './dsl/workflow-runner.js';
+export { addFeature, resolveFeatureScenarios } from './feature.js';
 export { template, type TemplateString } from './graph/template.js';
 export { pikkuWorkflowGraph, type PikkuWorkflowGraphConfig, type PikkuWorkflowGraphResult, } from './graph/wire-workflow-graph.js';
-export { validateWorkflowWiring, computeEntryNodeIds, } from './graph/graph-validation.js';
 export { pikkuWorkflowWorkerFunc, pikkuWorkflowOrchestratorFunc, pikkuWorkflowSleeperFunc, } from './workflow-queue-workers.js';
 export type { WorkflowStepInput as WorkflowStepQueueInput, PikkuWorkflowOrchestratorInput, PikkuWorkflowSleeperInput, } from './workflow-queue-workers.js';
-export type { WorkflowService, WorkflowQueueOptions, WorkflowServiceConfig, WorkflowPlannedStep, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, StepStatus, WorkflowRun, WorkflowRunStatus, StepState, WorkflowRunService, WorkflowRunMirror, CoreWorkflow, PikkuWorkflow, ContextVariable, WorkflowContext, WorkflowsMeta, WorkflowRuntimeMeta, WorkflowsRuntimeMeta, WorkflowStepInput, WorkflowOrchestratorInput, WorkflowSleeperInput, } from './workflow.types.js';
-export type { WorkflowStepOptions, WorkflowWireDoRPC, WorkflowWireDoInline, WorkflowWireSleep, WorkflowWireSuspend, WorkflowWireApproval, WorkflowApprovalOptions, ApprovalOutcome, InputSource, OutputBinding, RpcStepMeta, SimpleCondition, Condition, BranchCase, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SuspendStepMeta, ApprovalStepMeta, SetStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, PikkuScenarioWire, } from './workflow.types.js';
+export type { WorkflowService, WorkflowQueueOptions, WorkflowServiceConfig, WorkflowPlannedStep, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, StepStatus, WorkflowRun, WorkflowRunStatus, StepState, WorkflowRunService, WorkflowRunMirror, CoreWorkflow, CoreFeature, CoreFeatureScenario, FeatureMeta, FeatureMetaEntry, FeaturesMeta, FeaturePlanEntry, PikkuWorkflow, ContextVariable, WorkflowContext, WorkflowsMeta, WorkflowRuntimeMeta, WorkflowsRuntimeMeta, WorkflowStepInput, WorkflowOrchestratorInput, WorkflowSleeperInput, } from './workflow.types.js';
+export type { WorkflowStepOptions, WorkflowWireDoRPC, WorkflowWireDoInline, WorkflowWireSleep, WorkflowWireSuspend, WorkflowWireApproval, WorkflowApprovalOptions, ApprovalOutcome, InputSource, OutputBinding, RpcStepMeta, SimpleCondition, Condition, BranchCase, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SuspendStepMeta, ApprovalStepMeta, SetStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, ScenarioStepInvocation, ScenarioStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, PikkuScenarioWire, } from './workflow.types.js';
+export type { ScenarioStepPhase, ScenarioStepOptions, PikkuScenarioStepWire, ScenarioEnvironment, } from './scenario-step.types.js';
+export { requireActor, requireScenarioEnv } from './scenario-step-guards.js';
+export { pollUntil, type PollOptions } from './scenario-poll.js';
+export { createCookieJar } from './scenario-cookie-jar.js';
+export type { ScenarioCookieJar } from './scenario-cookie-jar.js';
+export type { ScenarioHttpResponse, ScenarioJsonRequest, } from '../../services/scenario-actors-service.js';
+export { readScenarioHttpResponse, postScenarioJson, } from '../../services/scenario-actors-service.js';
+export type { PikkuBrowserWire, TestIdSelector, ScenarioBrowserProvider, ScenarioBrowserFailure, } from './scenario-step.types.js';
+export { composeStepProse, renderStepTemplate } from './scenario-prose.js';

package/dist/wirings/workflow/index.js

@@ -7,10 +7,23 @@ export { deriveInvocationId, uuidv5 } from './workflow-invocation-id.js';
 export { buildRunTimeline, reconstructStateAt, reconstructFinalState, } from './run-timeline.js';
 // Internal registration functions (used by generated code)
 export { addWorkflow } from './dsl/workflow-runner.js';
+export { addFeature, resolveFeatureScenarios } from './feature.js';
 // Graph helpers (template, pikkuWorkflowGraph)
 export { template } from './graph/template.js';
 export { pikkuWorkflowGraph, } from './graph/wire-workflow-graph.js';
-// Graph validation and dynamic workflow utilities
-export { validateWorkflowWiring, computeEntryNodeIds, } from './graph/graph-validation.js';
 // Queue worker functions (registered by codegen, executed at runtime)
 export { pikkuWorkflowWorkerFunc, pikkuWorkflowOrchestratorFunc, pikkuWorkflowSleeperFunc, } from './workflow-queue-workers.js';
+// Narrows the optional halves of the step wire, with a message that says what to do
+export { requireActor, requireScenarioEnv } from './scenario-step-guards.js';
+// Waits for the target to catch up, without every step writing the loop again
+export { pollUntil } from './scenario-poll.js';
+// Persists cookies across a step's requests, the way a browser would
+export { createCookieJar } from './scenario-cookie-jar.js';
+export { readScenarioHttpResponse, postScenarioJson, } from '../../services/scenario-actors-service.js';
+/* ------------------------------------------------------------------ *
+ * Scenarios — reporting a run
+ *
+ * Used by the CLI reporter and the console, so the two render the same
+ * sentence for the same step. A step body needs none of it.
+ * ------------------------------------------------------------------ */
+export { composeStepProse, renderStepTemplate } from './scenario-prose.js';

package/dist/wirings/workflow/pikku-scenario-service.d.ts

@@ -0,0 +1,121 @@
+import { PikkuError } from '../../errors/error-handler.js';
+import { InMemoryWorkflowService } from '../../services/in-memory-workflow-service.js';
+import { type RunLifecycleContext, type WorkflowRunEngine, type WorkflowRunExtension } from './pikku-workflow-service.js';
+import type { PikkuWire } from '../../types/core.types.js';
+import type { ScenarioActors } from '../../services/scenario-actors-service.js';
+import type { ScenarioBrowserProvider, ScenarioEnvironment } from './scenario-step.types.js';
+import type { PikkuWorkflowWire, WorkflowQueueOptions } from './workflow.types.js';
+/**
+ * A workflow service with the scenario capability attached — the two lines
+ * `pikku scenario run` needs, in one call so no caller has to remember that the
+ * capability is installed rather than inherited.
+ *
+ * The in-memory service is the right engine because a scenario run is a single
+ * external process driving a deployed app over its real transport: there is
+ * nothing to persist and no second worker to resume it.
+ */
+export declare const createScenarioRunner: (options?: WorkflowQueueOptions) => {
+    workflowService: InMemoryWorkflowService;
+    scenarioService: PikkuScenarioService;
+};
+/**
+ * A scenario's `before` or `after` hook threw. The original error is kept as
+ * the `cause` so the failure that actually happened is never lost behind the
+ * label saying which phase it happened in.
+ */
+export declare class ScenarioHookError extends PikkuError {
+    readonly scenarioName: string;
+    readonly phase: 'before' | 'after';
+    constructor(scenarioName: string, phase: 'before' | 'after', cause: unknown);
+}
+/**
+ * The scenario capability, layered onto a workflow service rather than being
+ * one.
+ *
+ * Every scenario affordance — steps, actors, lifecycle hooks, the browser
+ * provider, the assertion wire members — lives here rather than on
+ * `PikkuWorkflowService`, because a bundler drops an unused *module* but never
+ * an unused class member: anything declared on the workflow service ships in
+ * every server built on Pikku, along with everything it imports. Scenarios only
+ * ever run from `pikku scenario run`, so the whole surface stays behind an
+ * import only that runner makes.
+ *
+ * It is not a workflow service because a scenario is not a different kind of
+ * run — it is the same durable run with a step vocabulary on top. What it
+ * needs from the engine it gets through the narrow `WorkflowRunEngine` handle,
+ * which is why recording a step never became public API.
+ *
+ * ```ts
+ * const workflowService = new InMemoryWorkflowService()
+ * const scenarioService = workflowService.setRunExtension(
+ *   (engine) => new PikkuScenarioService(engine)
+ * )
+ * ```
+ */
+export declare class PikkuScenarioService implements WorkflowRunExtension {
+    private readonly engine;
+    private runActors;
+    private scenarioBrowserProvider?;
+    private scenarioEnvironment?;
+    constructor(engine: WorkflowRunEngine);
+    /**
+     * Registered by `@pikku/playwright` (or any other driver) before a scenario
+     * runs. Absent means browser steps cannot run, which the CLI checks up front
+     * so a run fails fast rather than mid-flow.
+     */
+    setScenarioBrowserProvider(provider: ScenarioBrowserProvider | undefined): void;
+    getScenarioBrowserProvider(): ScenarioBrowserProvider | undefined;
+    /**
+     * The environment scenario steps run against, set once by the runner. It is
+     * per-service rather than per-run because a runner process targets exactly
+     * one environment for every scenario it executes.
+     */
+    setScenarioEnvironment(env: ScenarioEnvironment | undefined): void;
+    getScenarioEnvironment(): ScenarioEnvironment | undefined;
+    attachRunContext(runId: string, workflowMeta: any, options?: {
+        actors?: ScenarioActors;
+    }): Promise<void>;
+    detachRunContext(runId: string): void;
+    decorateRunWire(wire: PikkuWire, context: {
+        runId: string;
+        workflowMeta: any;
+        workflowWire: PikkuWorkflowWire;
+    }): void;
+    onBeforeRunFunc(context: RunLifecycleContext): Promise<void>;
+    onAfterRunFunc(context: RunLifecycleContext, outcome: 'completed' | 'failed' | 'interrupted', failure: unknown): Promise<void>;
+    /**
+     * Hooks are a scenario affordance only: a plain workflow is durable and
+     * resumable, so a callback that reruns on every replay has no honest meaning
+     * there.
+     */
+    private scenarioHooks;
+    /**
+     * Run a scenario `before`/`after` hook.
+     *
+     * A hook is not a pikku function: it has no id, no meta and no schema, so it
+     * cannot go through `runPikkuFunc` and the runner records nothing for it. It
+     * gets exactly what the scenario body gets — the same wire (so `actors` is
+     * how it reaches the app), and singleton services composed with this
+     * invocation's wire services — and nothing else.
+     */
+    private runScenarioHook;
+    /**
+     * Build HTTP scenario actors for a run started without them; undefined when
+     * SCENARIO_ACTOR_SECRET or the API URL is missing.
+     *
+     * The actor client is imported lazily so that even a runner bundle only pays
+     * for the AI persona conversation loop it pulls in when a scenario actually
+     * signs an actor in.
+     */
+    resolveScenarioActors(): Promise<ScenarioActors | undefined>;
+    decorateWorkflowWire(wire: PikkuWorkflowWire, context: {
+        name: string;
+        runId: string;
+        rpcService: any;
+        addonNamespace?: string | null;
+    }): void;
+    private scenarioStep;
+    private scenarioStepConfig;
+    private scenarioStepDescription;
+    private requiresBrowser;
+}