@pikku/cli 0.12.104 → 0.12.107

package/dist/.pikku/workflow/pikku-workflow-types.gen.d.ts

@@ -1,51 +1,28 @@
 /**
- * This file was generated by @pikku/cli@0.12.104
+ * This file was generated by @pikku/cli@0.12.107
  */
 import { WorkflowCancelledException } from '@pikku/core/workflow';
-import { template } from '@pikku/core/workflow';
-import { type PikkuWorkflowGraphConfig, type PikkuWorkflowGraphResult } from '@pikku/core/workflow';
+import type { PikkuWorkflowGraphConfig, PikkuWorkflowGraphResult } from '@pikku/core/workflow';
 import type { PikkuWorkflowWire, WorkflowStepOptions } from '@pikku/core/workflow';
-import type { PikkuScenarioWire, ScenarioStepOptions } from '@pikku/core/scenario';
 export { WorkflowCancelledException };
-import type { PikkuFunctionSessionless, PikkuFunctionConfig, WiredServices } from '../function/pikku-function-types.gen.js';
+import type { PikkuFunctionSessionless, PikkuFunctionConfig } from '../function/pikku-function-types.gen.js';
 import type { FlattenedRPCMap } from '../rpc/pikku-rpc-wirings-map.internal.gen.d.js';
 import type { FlattenedWorkflowMap } from './pikku-workflow-map.gen.d.js';
 import type { AgentMap as FlattenedAgentMap } from '../agent/pikku-agent-map.gen.d.js';
-import type { FlattenedScenarioStepMap } from './pikku-scenario-step-map.gen.d.js';
-import type { TypedPersonas } from './pikku-personas.gen.js';
-export type { TypedPersonas };
-export { template };
 export interface TypedWorkflow extends PikkuWorkflowWire {
     do<K extends keyof FlattenedRPCMap>(stepName: string, rpcName: K, data: FlattenedRPCMap[K]['input'], options?: WorkflowStepOptions): Promise<FlattenedRPCMap[K]['output']>;
     do<K extends keyof FlattenedWorkflowMap>(stepName: string, workflowName: K, data: FlattenedWorkflowMap[K]['input'], options?: WorkflowStepOptions): Promise<FlattenedWorkflowMap[K]['output']>;
     do<T>(stepName: string, fn: () => T | Promise<T>, options?: WorkflowStepOptions): Promise<T>;
 }
-/**
- * The typed half of a scenario wire: `given`/`when`/`then`, narrowed to the
- * names declared by `pikkuScenarioStep` in this project. `given` and `when`
- * differ only in the prose the reporter renders; `then` additionally makes the
- * step's bindings witnesses rather than alternatives.
- */
-export interface TypedScenarioSteps {
-    given<K extends keyof FlattenedScenarioStepMap>(stepName: string, stepFunc: K, data?: FlattenedScenarioStepMap[K]['input'], options?: ScenarioStepOptions): Promise<FlattenedScenarioStepMap[K]['output']>;
-    when<K extends keyof FlattenedScenarioStepMap>(stepName: string, stepFunc: K, data?: FlattenedScenarioStepMap[K]['input'], options?: ScenarioStepOptions): Promise<FlattenedScenarioStepMap[K]['output']>;
-    then<K extends keyof FlattenedScenarioStepMap>(stepName: string, stepFunc: K, data?: FlattenedScenarioStepMap[K]['input'], options?: ScenarioStepOptions): Promise<FlattenedScenarioStepMap[K]['output']>;
-}
-/** `Out` types `scenario.context`. */
-export type TypedScenario<Out = unknown> = TypedWorkflow & Omit<PikkuScenarioWire<Out>, keyof PikkuWorkflowWire | keyof TypedScenarioSteps> & TypedScenarioSteps;
 import type { StandardSchemaV1 } from '@standard-schema/spec';
-import type { InferSchemaOutput, PikkuPermission, PikkuMiddleware, NodeConfig, PikkuApprovalDescription } from '../function/pikku-function-types.gen.js';
+import type { InferSchemaOutput, NodeConfig, PikkuApprovalDescription } from '../function/pikku-function-types.gen.js';
+import type { PikkuPermission } from '../auth/pikku-auth-types.gen.js';
+import type { PikkuMiddleware } from '../middleware/pikku-middleware-types.gen.js';
 import type { ScopeId } from '../scopes/pikku-scopes.gen.js';
 import { PikkuError } from '@pikku/core/errors';
-import type { CorePermissionGroup } from '@pikku/core';
+import type { CorePermissionGroup } from '@pikku/core/function';
 export type PikkuFunctionWorkflow<In = unknown, Out = never> = PikkuFunctionSessionless<In, Out, 'workflow'>;
-/**
- * `Ctx` types `scenario.context`, defaulting to the body's own output. A hook
- * returns void but shares the scenario's context, so it passes that scenario's
- * output here instead.
- */
-export type PikkuFunctionScenario<In = unknown, Out = never, Ctx = Out> = PikkuFunctionSessionless<In, Out, 'scenario' | 'actors', WiredServices, Ctx>;
-export type PikkuWorkflowConfigWithSchema<InputSchema extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined> = {
+type PikkuWorkflowConfigWithSchema<InputSchema extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined> = {
     title?: string;
     description?: string;
     tags?: string[];
@@ -58,6 +35,12 @@ export type PikkuWorkflowConfigWithSchema<InputSchema extends StandardSchemaV1 |
     readonly?: boolean;
     approvalRequired?: boolean;
     approvalDescription?: InputSchema extends StandardSchemaV1 ? PikkuApprovalDescription<InferSchemaOutput<InputSchema>> : never;
+    middleware?: PikkuMiddleware[];
+    input?: InputSchema;
+    output?: OutputSchema;
+    node?: NodeConfig;
+    errors?: Array<typeof PikkuError>;
+    inline?: boolean;
     func: PikkuFunctionWorkflow<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown>;
     auth?: boolean;
     /**
@@ -66,242 +49,11 @@ export type PikkuWorkflowConfigWithSchema<InputSchema extends StandardSchemaV1 |
      */
     scopes?: ScopeId[];
     permissions?: InputSchema extends StandardSchemaV1 ? CorePermissionGroup<PikkuPermission<InferSchemaOutput<InputSchema>>> : undefined;
-    middleware?: PikkuMiddleware[];
-    input?: InputSchema;
-    output?: OutputSchema;
-    node?: NodeConfig;
-    errors?: Array<typeof PikkuError>;
-    inline?: boolean;
 };
 export declare function pikkuWorkflowFunc<InputSchema extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined>(config: PikkuWorkflowConfigWithSchema<InputSchema, OutputSchema>): PikkuFunctionConfig<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'workflow', PikkuFunctionWorkflow<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown>, InputSchema, OutputSchema>;
 export declare function pikkuWorkflowFunc<In, Out = unknown>(func: PikkuFunctionWorkflow<In, Out> | PikkuFunctionConfig<In, Out, 'workflow', PikkuFunctionWorkflow<In, Out>>): PikkuFunctionConfig<In, Out, 'workflow'>;
 export declare function pikkuWorkflowComplexFunc<InputSchema extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined>(config: PikkuWorkflowConfigWithSchema<InputSchema, OutputSchema>): PikkuFunctionConfig<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'workflow', PikkuFunctionWorkflow<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown>, InputSchema, OutputSchema>;
 export declare function pikkuWorkflowComplexFunc<In, Out = unknown>(func: PikkuFunctionWorkflow<In, Out> | PikkuFunctionConfig<In, Out, 'workflow', PikkuFunctionWorkflow<In, Out>>): PikkuFunctionConfig<In, Out, 'workflow'>;
-export type PikkuScenarioConfigWithSchema<InputSchema extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined> = Omit<PikkuWorkflowConfigWithSchema<InputSchema, OutputSchema>, 'func' | 'auth' | 'scopes' | 'permissions'> & {
-    func: PikkuFunctionScenario<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown>;
-    /**
-     * Runs before the scenario body. Same signature as `func`, but its return
-     * value is discarded — a hook is setup, not a step, so it is never recorded
-     * on the ladder. Throwing skips the body and fails the run; `after` still
-     * runs.
-     */
-    before?: PikkuScenarioHook<InputSchema, OutputSchema>;
-    /**
-     * Always runs after the scenario body, in a `finally`, whether it passed or
-     * failed. Throwing fails a run that would otherwise have passed; on an
-     * already-failed run it attaches as the `cause` and never replaces the
-     * original error. Reads `scenario.context` for whatever the body managed to
-     * record before it stopped.
-     */
-    after?: PikkuScenarioHook<InputSchema, OutputSchema>;
-    /**
-     * Why this scenario is held out of a default run, stated where the scenario
-     * is. The scenario still appears in the plan and is reported as skipped
-     * rather than quietly omitted; naming it directly with `--flows` runs it
-     * anyway.
-     */
-    skip?: string;
-};
-/**
- * A scenario lifecycle hook: the scenario's own `(services, data, wire)`
- * signature with its result discarded. `OutputSchema` types
- * `scenario.context` while the return type stays `void`.
- */
-export type PikkuScenarioHook<InputSchema extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined> = PikkuFunctionScenario<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, void, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown>;
-/**
- * Declares a scenario hook. Returns the function verbatim — a hook is never
- * registered, so this exists purely to give an inline hook a call site to be
- * contextually typed from, the way every other pikku primitive is.
- */
-export declare function pikkuScenarioHook<In = unknown, Ctx = unknown>(hook: PikkuFunctionScenario<In, void, Ctx>): PikkuFunctionScenario<In, void, Ctx>;
-/**
- * A scenario: a complex workflow that drives the app the way users do.
- * Steps run as actors over the REAL transport — `scenario.do(step, rpc,
- * data, { actor: actors.yasser })` — so flows double as e2e tests and
- * staged/production health checks (no state reset; scope what you create).
- */
-export declare function pikkuScenario<InputSchema extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined>(config: PikkuScenarioConfigWithSchema<InputSchema, OutputSchema>): PikkuFunctionConfig<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'scenario' | 'actors', PikkuFunctionScenario<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown>, InputSchema, OutputSchema>;
-export declare function pikkuScenario<In, Out = unknown>(func: PikkuFunctionScenario<In, Out> | PikkuFunctionConfig<In, Out, 'scenario' | 'actors', PikkuFunctionScenario<In, Out>>): PikkuFunctionConfig<In, Out, 'scenario' | 'actors'>;
-/**
- * A scenario as a feature references it. Any `pikkuScenario` export is
- * assignable; `In` is recovered from it so the paired form's `data` is
- * checked against that scenario's own input.
- */
-export type PikkuScenarioRef<In = any, Out = any> = PikkuFunctionConfig<In, Out, 'scenario' | 'actors', PikkuFunctionScenario<In, Out>, any, any>;
-/**
- * One entry in a feature's `scenarios` list, validated against itself: a bare
- * scenario, or a scenario paired with the input to run it with. The paired form
- * is gherkin's `Examples:` written as an ordinary loop.
- */
-export type PikkuFeatureEntry<Entry> = Entry extends {
-    scenario: PikkuScenarioRef<infer In>;
-} ? {
-    scenario: PikkuScenarioRef<In>;
-    data: In;
-} : Entry extends PikkuScenarioRef ? Entry : never;
-export type PikkuFeatureConfig<Scenarios extends readonly unknown[]> = {
-    /** Human-readable name. The export identifier is the id. */
-    name: string;
-    description?: string;
-    tags?: string[];
-    scenarios: {
-        [K in keyof Scenarios]: PikkuFeatureEntry<Scenarios[K]>;
-    };
-    /**
-     * Runs ONCE before the whole group — not before each scenario. Per-scenario
-     * setup is the scenario's own `before`; gherkin's `Background:` is
-     * deliberately not expressible here.
-     */
-    before?: PikkuScenarioHook;
-    after?: PikkuScenarioHook;
-};
-/**
- * A feature: an ordered group of scenarios, mirroring gherkin's Feature ↔
- * Scenario structure. Scenarios are referenced by imported identifier, so a
- * renamed or deleted scenario is a compile error rather than a silent skip.
- *
- * A scenario does not have to belong to a feature — a void-input scenario
- * still runs standalone.
- *
- * ```ts
- * export const credentialFeature = pikkuFeature({
- *   name: 'Credential API',
- *   tags: ['credential'],
- *   before: startsMockOAuthServer,
- *   after: stopsMockOAuthServer,
- *   scenarios: [
- *     credentialLazyLoadScenario,
- *     ...['stripe', 'google'].map((name) => ({
- *       scenario: credentialRoundTripScenario,
- *       data: { name },
- *     })),
- *   ],
- * })
- * ```
- */
-export declare function pikkuFeature<const Scenarios extends readonly unknown[]>(config: PikkuFeatureConfig<Scenarios>): PikkuFeatureConfig<Scenarios>;
-/**
- * One surface's implementation of a step.
- *
- * Each binding is typed independently, so a browser binding gets a non-optional
- * `wire.browser` and a cli binding a non-optional `wire.cli` without either
- * leaking into the other.
- */
-export type PikkuFunctionScenarioStep<In = unknown, Out = never, Surface extends 'browser' | 'cli' | 'default' = 'default'> = PikkuFunctionSessionless<In, Out, Surface extends 'default' ? 'scenarioStep' : 'scenarioStep' | Surface>;
-export type PikkuScenarioStepConfigWithSchema<InputSchema extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined> = {
-    /** Registered name — this is the string `scenario.given()` references. */
-    name: string;
-    /**
-     * What this step does, for the console and for whoever reads the source. It
-     * is also the fallback prose when no `template` is declared, in which case a
-     * reporter renders "Given the shopper buys an apple". Defaults to the call
-     * site's step name.
-     */
-    description?: string;
-    /**
-     * The prose a reporter renders for this step, with `{placeholders}` filled
-     * from the input the step was called with — `'sees {packageName}'` reports as
-     * "Then the admin sees @pikku/addon-todos". Every input field should appear,
-     * so the report names the values under test rather than repeating one
-     * sentence per call site.
-     */
-    template?: string;
-    title?: string;
-    tags?: string[];
-    input?: InputSchema;
-    output?: OutputSchema;
-    errors?: Array<typeof PikkuError>;
-    /**
-     * Drive this step through a real browser, as a human would. The runner
-     * provisions a window for the step's actor first — which makes an actor
-     * mandatory — and `wire.browser` is non-optional inside it.
-     *
-     * Compose shared utilities here rather than writing raw clicks: the step says
-     * what the actor is doing, the utilities say how.
-     */
-    browser?: PikkuFunctionScenarioStep<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'browser'>;
-    /** Drive this step remotely, over the websocket. */
-    cli?: PikkuFunctionScenarioStep<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'cli'>;
-    /**
-     * The server-side path — the fast suite, and the floor every other surface
-     * falls back to.
-     *
-     * On a `then`, this is not an alternative to the other bindings but a second
-     * **witness**: the run executes every binding it has and fails if they
-     * disagree, because "the row says paid" and "the page says paid" are different
-     * claims and the gap between them is the bug nobody catches.
-     */
-    default?: PikkuFunctionScenarioStep<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'default'>;
-};
-export type PikkuScenarioStepConfig<In, Out> = Omit<PikkuScenarioStepConfigWithSchema<undefined, undefined>, 'browser' | 'cli' | 'default' | 'input' | 'output'> & {
-    browser?: PikkuFunctionScenarioStep<In, Out, 'browser'>;
-    cli?: PikkuFunctionScenarioStep<In, Out, 'cli'>;
-    default?: PikkuFunctionScenarioStep<In, Out, 'default'>;
-};
-/**
- * A named, reusable scenario step, declaring one implementation per surface an
- * actor can drive it through.
- *
- * The step's identity is what the actor is trying to do; which surface carries
- * it out is a binding. That is what lets one ladder run through a real browser,
- * over the websocket, or entirely server-side — and what makes "how much of this
- * flow can a human actually reach" a number rather than a guess.
- *
- * Steps are deliberately NOT registered as RPCs: a browser-driving step must
- * never be network-callable.
- */
-export declare function pikkuScenarioStep<InputSchema extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined>(config: PikkuScenarioStepConfigWithSchema<InputSchema, OutputSchema>): PikkuFunctionConfig<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'scenarioStep' | 'browser' | 'cli', PikkuFunctionScenarioStep<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'browser' | 'cli' | 'default'>, InputSchema, OutputSchema>;
-export declare function pikkuScenarioStep<In, Out = unknown>(config: PikkuScenarioStepConfig<In, Out>): PikkuFunctionConfig<In, Out, 'scenarioStep' | 'browser' | 'cli'>;
-/**
- * What a step declares when nobody drives it: one implementation, and no
- * surfaces to choose between.
- *
- * `func` rather than `default` is the point. `default` means *the fallback when
- * no other surface applies*, which implies others could exist; `func` says
- * structurally that there is one way this happens. That also keeps the phase
- * rule coherent — an assertion runs every witness it has and fails if they
- * disagree, and this has exactly one by construction.
- */
-export type PikkuSubjectScenarioStepConfigWithSchema<InputSchema extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined> = Omit<PikkuScenarioStepConfigWithSchema<InputSchema, OutputSchema>, 'browser' | 'cli' | 'default'> & {
-    func: PikkuFunctionScenarioStep<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'default'>;
-};
-export type PikkuSubjectScenarioStepConfig<In, Out> = Omit<PikkuScenarioStepConfig<In, Out>, 'browser' | 'cli' | 'default'> & {
-    func: PikkuFunctionScenarioStep<In, Out, 'default'>;
-};
-/**
- * A step in which the app acts on itself — "Given the platform has expired the
- * trial".
- *
- * The grammatical subject of that sentence is not a user of your app; it **is**
- * your app, which is why it is its own declaration rather than a persona with an
- * asterisk. A persona is a person.
- *
- * Local-test-only, and never in a virtual user's catalogue: a virtual user that
- * could expire its own trial is manufacturing the outcome it exists to discover.
- */
-export declare function pikkuPlatformScenarioStep<InputSchema extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined>(config: PikkuSubjectScenarioStepConfigWithSchema<InputSchema, OutputSchema>): PikkuFunctionConfig<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'scenarioStep', PikkuFunctionScenarioStep<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'default'>, InputSchema, OutputSchema>;
-export declare function pikkuPlatformScenarioStep<In, Out = unknown>(config: PikkuSubjectScenarioStepConfig<In, Out>): PikkuFunctionConfig<In, Out, 'scenarioStep'>;
-/**
- * A step in which a third-party system acts — "Given Stripe's webhook arrives",
- * "When Mailgun bounces it".
- *
- * `addon` names the addon that wraps that service, the same name its
- * `wireAddon` declares. These steps *are* the mock its consumers currently
- * hand-write: shipped by the addon author, maintained with the addon, and the
- * same artifact that appears in the prose.
- *
- * Note that arranging and asserting are different — "Stripe's webhook arrives"
- * stubs, "Then Stripe was charged" asserts, and only the first is a stub.
- *
- * Local-test-only, and never in a virtual user's catalogue: one that could
- * invoke this would forge its own payment success.
- */
-export declare function pikkuAddonScenarioStep<InputSchema extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined>(config: PikkuSubjectScenarioStepConfigWithSchema<InputSchema, OutputSchema> & {
-    addon: string;
-}): PikkuFunctionConfig<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'scenarioStep', PikkuFunctionScenarioStep<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'default'>, InputSchema, OutputSchema>;
-export declare function pikkuAddonScenarioStep<In, Out = unknown>(config: PikkuSubjectScenarioStepConfig<In, Out> & {
-    addon: string;
-}): PikkuFunctionConfig<In, Out, 'scenarioStep'>;
 type TypedRef<T> = {
     $ref: string;
     path?: string;
@@ -330,10 +82,16 @@ type RefFunction<FuncMap extends Record<string, string>> = {
     (nodeId: 'trigger' | '$item', path?: string): TypedRef<unknown>;
 };
 type TemplateFunction = (templateStr: string, refs: TypedRef<unknown>[]) => TemplateString;
+type ItemFunction = (path?: string) => TypedRef<unknown>;
+type ForEachConfig<FuncMap extends Record<string, string>> = Extract<keyof FuncMap, string> | ((ref: RefFunction<FuncMap>) => TypedRef<unknown>);
 type GraphNodeConfigMap<FuncMap extends Record<string, string>> = {
     [K in Extract<keyof FuncMap, string>]?: {
         next?: NextConfig<Extract<keyof FuncMap, string>>;
-        input?: NodeInputType<FuncMap, K> | (() => NodeInputType<FuncMap, K>) | ((ref: RefFunction<FuncMap>, template: TemplateFunction) => NodeInputType<FuncMap, K>);
+        /** Run this node once per element of an upstream array. Its result becomes the ordered array of per-item results. */
+        forEach?: ForEachConfig<FuncMap>;
+        /** How the per-item instances of a forEach node run. Defaults to 'parallel'. */
+        mode?: 'parallel' | 'sequential';
+        input?: NodeInputType<FuncMap, K> | (() => NodeInputType<FuncMap, K>) | ((ref: RefFunction<FuncMap>, template: TemplateFunction, $item: ItemFunction) => NodeInputType<FuncMap, K>);
         onError?: Extract<keyof FuncMap, string> | Extract<keyof FuncMap, string>[];
         /** Free-text node documentation. Non-semantic — excluded from graphHash. */
         notes?: string;

package/dist/.pikku/workflow/pikku-workflow-types.gen.js

@@ -1,78 +1,15 @@
 /**
- * This file was generated by @pikku/cli@0.12.104
+ * This file was generated by @pikku/cli@0.12.107
  */
 import { WorkflowCancelledException } from '@pikku/core/workflow';
-import { template } from '@pikku/core/workflow';
-import { pikkuWorkflowGraph as corePikkuWorkflowGraph, } from '@pikku/core/workflow';
+import { pikkuWorkflowGraph as corePikkuWorkflowGraph } from '@pikku/core/workflow';
 export { WorkflowCancelledException };
-export { template };
 export function pikkuWorkflowFunc(func) {
     return typeof func === 'function' ? { func } : func;
 }
 export function pikkuWorkflowComplexFunc(func) {
     return typeof func === 'function' ? { func } : func;
 }
-/**
- * Declares a scenario hook. Returns the function verbatim — a hook is never
- * registered, so this exists purely to give an inline hook a call site to be
- * contextually typed from, the way every other pikku primitive is.
- */
-export function pikkuScenarioHook(hook) {
-    return hook;
-}
-export function pikkuScenario(func) {
-    return typeof func === 'function' ? { func } : func;
-}
-/**
- * A feature: an ordered group of scenarios, mirroring gherkin's Feature ↔
- * Scenario structure. Scenarios are referenced by imported identifier, so a
- * renamed or deleted scenario is a compile error rather than a silent skip.
- *
- * A scenario does not have to belong to a feature — a void-input scenario
- * still runs standalone.
- *
- * ```ts
- * export const credentialFeature = pikkuFeature({
- *   name: 'Credential API',
- *   tags: ['credential'],
- *   before: startsMockOAuthServer,
- *   after: stopsMockOAuthServer,
- *   scenarios: [
- *     credentialLazyLoadScenario,
- *     ...['stripe', 'google'].map((name) => ({
- *       scenario: credentialRoundTripScenario,
- *       data: { name },
- *     })),
- *   ],
- * })
- * ```
- */
-export function pikkuFeature(config) {
-    return config;
-}
-export function pikkuScenarioStep(config) {
-    const surfaces = ['browser', 'cli', 'default'].filter((surface) => typeof config[surface] === 'function');
-    if (surfaces.length === 0) {
-        throw new Error(`[scenario] step '${config.name}' declares no surface bindings. Add at least a \`default\` (server-side) implementation.`);
-    }
-    return {
-        ...config,
-        surfaces,
-        // The runner sets the surface on the wire and calls this once per binding it
-        // resolved — every witness of a `then`, exactly one for an action step.
-        func: (services, data, wire) => {
-            const surface = wire?.scenarioStep?.surface ?? 'default';
-            const binding = config[surface] ?? config.default;
-            return binding(services, data, wire);
-        },
-    };
-}
-export function pikkuPlatformScenarioStep(config) {
-    return { ...config, surfaces: ['default'] };
-}
-export function pikkuAddonScenarioStep(config) {
-    return { ...config, surfaces: ['default'] };
-}
 export function pikkuWorkflowGraph(config) {
     return corePikkuWorkflowGraph(config);
 }

package/dist/.pikku/workflow/pikku-workflow-wirings-meta.gen.js

@@ -1,7 +1,7 @@
 /**
- * This file was generated by @pikku/cli@0.12.104
+ * This file was generated by @pikku/cli@0.12.107
  */
-import { pikkuState } from '@pikku/core/ecosystem';
+import { pikkuState } from '@pikku/core/state';
 import allWorkflowMeta from './meta/allWorkflow.gen.json' with { type: 'json' };
 const workflowsMeta = {
     'allWorkflow': allWorkflowMeta,

package/dist/.pikku/workflow/pikku-workflow-wirings.gen.d.ts

@@ -1,2 +1 @@
 import './pikku-workflow-wirings-meta.gen.js';
-export type WorkflowNames = 'allWorkflow';

package/dist/.pikku/workflow/pikku-workflow-wirings.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.104
+ * This file was generated by @pikku/cli@0.12.107
  */
 import { addWorkflow } from '@pikku/core/workflow';
 import './pikku-workflow-wirings-meta.gen.js';

package/dist/bin/pikku-bin.mjs

@@ -11,8 +11,8 @@ async function checkForUpdate() {
     })
     if (!res.ok) return
     const { version: latest } = await res.json()
-    if (latest !== '0.12.104') {
-      process.stderr.write(`\n  Update available  0.12.104 → ${latest}\n  brew upgrade pikku  or  npm install -g @pikku/cli\n\n`)
+    if (latest !== '0.12.107') {
+      process.stderr.write(`\n  Update available  0.12.107 → ${latest}\n  brew upgrade pikku  or  npm install -g @pikku/cli\n\n`)
     }
   } catch {}
 }

package/dist/src/cli.wiring.js

@@ -29,6 +29,8 @@ import { scopesPrune } from './functions/commands/scopes-prune.js';
 import { rolesAudit } from './functions/commands/roles-audit.js';
 import { rolesPrune } from './functions/commands/roles-prune.js';
 import { pikkuAudit } from './functions/commands/audit.js';
+import { pikkuSemver } from './functions/commands/semver.js';
+import { renderSemver } from './functions/commands/semver-render.js';
 import { validate, renderValidate } from './functions/commands/validate.js';
 import { knowledgeValidate, renderKnowledgeValidate, } from './functions/commands/knowledge-validate.js';
 import { knowledgeIndex, renderKnowledgeIndex, } from './functions/commands/knowledge-index.js';
@@ -39,6 +41,8 @@ import { pikkuVersionsInit } from './functions/commands/versions-init.js';
 import { pikkuEmailsInit } from './functions/commands/emails-init.js';
 import { pikkuVersionsCheck } from './functions/commands/versions-check.js';
 import { pikkuVersionsUpdate } from './functions/commands/versions-update.js';
+import { pikkuUpdate } from './functions/commands/update.js';
+import { renderUpdate } from './functions/commands/update-render.js';
 import { pikkuNewFunction } from './functions/commands/new-function.js';
 import { pikkuNewWiring } from './functions/commands/new-wiring.js';
 import { pikkuNewMiddleware } from './functions/commands/new-middleware.js';
@@ -139,51 +143,66 @@ wireCLI({
                 },
                 filter: {
                     description: 'Named filter(s) from pikku.config.json filters map (comma-separated)',
+                    type: 'string[]',
                 },
                 tags: {
                     description: 'Include functions by tags (comma-separated)',
                     short: 't',
+                    type: 'string[]',
                 },
                 wires: {
                     description: 'Filter direct wirings by category (comma-separated)',
+                    type: 'string[]',
                 },
                 excludeWires: {
                     description: 'Exclude direct wirings by category (comma-separated)',
+                    type: 'string[]',
                 },
                 excludeTags: {
                     description: 'Exclude functions by tags (comma-separated)',
+                    type: 'string[]',
                 },
                 directories: {
                     description: 'Include functions by directories (comma-separated)',
                     short: 'd',
+                    type: 'string[]',
                 },
                 excludeDirectories: {
                     description: 'Exclude functions by directories (comma-separated)',
+                    type: 'string[]',
                 },
                 httpMethods: {
                     description: 'Include HTTP routes by methods (comma-separated)',
+                    type: 'string[]',
                 },
                 excludeHttpMethods: {
                     description: 'Exclude HTTP routes by methods (comma-separated)',
+                    type: 'string[]',
                 },
                 httpRoutes: {
                     description: 'Include HTTP routes by route patterns (comma-separated)',
+                    type: 'string[]',
                 },
                 excludeHttpRoutes: {
                     description: 'Exclude HTTP routes by route patterns (comma-separated)',
+                    type: 'string[]',
                 },
                 names: {
                     description: 'Include functions by name patterns (supports wildcards)',
                     short: 'n',
+                    type: 'string[]',
                 },
                 excludeNames: {
                     description: 'Exclude functions by name patterns (supports wildcards)',
+                    type: 'string[]',
                 },
                 target: {
                     description: 'Include functions by deploy target (comma-separated: serverless, server)',
+                    type: 'string[]',
                 },
                 excludeTarget: {
                     description: 'Exclude functions by deploy target (comma-separated: serverless, server)',
+                    type: 'string[]',
                 },
                 forceRelativeImports: {
                     description: 'Emit relative imports even when packageMappings would apply (used by per-unit deploy codegen)',
@@ -205,6 +224,52 @@ wireCLI({
                 },
             },
         }),
+        update: pikkuCLICommand({
+            func: pikkuUpdate,
+            render: renderUpdate,
+            description: 'Report which @pikku/* dependencies can be updated, and the peers those updates need. Reports only until --update is passed',
+            options: {
+                update: {
+                    description: 'Write the new ranges into every package.json covered by the run. Without it, update only reports',
+                    default: false,
+                },
+                updatePeers: {
+                    description: "Also write the ranges unsatisfied peers require (e.g. bumping 'ai' for @pikku/ai-vercel). Implies --update, and can cross a major version of a third-party package",
+                    default: false,
+                },
+                install: {
+                    description: 'After writing, run an install with the package manager the lockfile names. --no-install leaves node_modules alone',
+                    default: true,
+                },
+                tag: {
+                    description: "Dist-tag to update to (default: 'latest')",
+                    default: 'latest',
+                },
+                registry: {
+                    description: 'Registry to read versions from (default: npm_config_registry, else https://registry.npmjs.org)',
+                },
+            },
+        }),
+        semver: pikkuCLICommand({
+            func: pikkuSemver,
+            render: renderSemver,
+            description: "Derive the release semver by comparing this build's surface against a deployed one; writes .pikku/changes.gen.json",
+            options: {
+                against: {
+                    description: 'Baseline to compare against: a .pikku directory, a snapshot file, or a snapshot URL',
+                },
+                emit: {
+                    description: "Produce this build's surface snapshot instead of comparing — publish it to serve as a baseline. Pair with --out; without it the snapshot goes to stdout after the CLI banner",
+                    default: false,
+                },
+                out: {
+                    description: 'Where to write the output (defaults to .pikku/changes.gen.json; with --emit, stdout)',
+                },
+                failOn: {
+                    description: 'Exit non-zero when the verdict is at or above this level: major, minor or patch',
+                },
+            },
+        }),
         watch: pikkuCLICommand({
             func: watch,
             description: 'Watch for file changes and regenerate automatically',
@@ -464,10 +529,6 @@ wireCLI({
                             description: 'Reset/snapshot server coverage per scenario (target must run with --coverage); writes coverage/scenario-coverage.json',
                             default: false,
                         },
-                        browser: {
-                            description: 'Shorthand for --run default when false: takes the server-side path instead of driving a browser',
-                            default: true,
-                        },
                         run: {
                             description: "Which surface every actor drives the system through: 'browser' (as a human), 'cli' (over the websocket), or 'default' (server-side, the fast path)",
                             default: 'default',
@@ -493,14 +554,15 @@ wireCLI({
                             default: false,
                         },
                         video: {
-                            description: 'Record a video per scenario alongside the screenshots (implies --screenshots)',
-                            default: false,
+                            description: 'Which scenarios keep their recording: "failed" (the default), "all", or "off" to record nothing. Recording is decided when a window opens, before the outcome is known, so keeping only failures still records every scenario and discards the passes',
+                            choices: ['off', 'failed', 'all'],
+                            default: 'failed',
                         },
                         apiUrl: {
                             description: "Override the environment's apiUrl for this run — for a target that only exists at run time, such as a freshly deployed sandbox",
                         },
                         appUrl: {
-                            description: "Override the environment's appUrl for this run (the frontend browser steps navigate against)",
+                            description: "Override the environment's appUrl for this run (the frontend browser steps navigate against). One url for everybody, or `<app>=<url>` pairs for a product whose personas sign into different apps — comma-separated, and a bare url is the fallback",
                         },
                     },
                 }),