@itmetsam/samurai-framework 0.3.0 → 0.5.0

package/dist/cli/flow-reporter.d.ts

@@ -1,10 +1,12 @@
-import { type FlowFile } from "../flows/core/index.js";
+import { type AnyNodeDefinition, type FlowFile } from "../flows/core/index.js";
 import { type FlowEvent } from "../flows/run/index.js";
 export interface FlowReporterOptions {
     flow: FlowFile;
     write: (text: string) => void;
     /** Colour with ANSI codes */
     color: boolean;
+    /** Definitions of the project's steps, for their labels. @default the built-in steps */
+    steps?: readonly AnyNodeDefinition[];
 }
 /** Prints a flow run for a person: one line per node as it ends, then a count. Start and End are not listed. */
 export declare class FlowReporter {
@@ -12,8 +14,9 @@ export declare class FlowReporter {
     private readonly paint;
     private readonly nodes;
     private readonly flow;
+    private readonly steps;
     private started;
-    constructor({ flow, write, color }: FlowReporterOptions);
+    constructor({ flow, write, color, steps }: FlowReporterOptions);
     private shapeOf;
     private listed;
     private nameOf;

package/dist/cli/flow-reporter.js

@@ -1,11 +1,13 @@
 import { nodeDef, } from "../flows/core/index.js";
 import { maskSecrets as maskText, } from "../flows/run/index.js";
+import { STEP_NODES } from "../flows/steps/index.js";
 const took = (ms) => ms < 1000 ? `${Math.round(ms)}ms` : `${(ms / 1000).toFixed(1)}s`;
 const SKIPPED_BY_SHAPE = new Set(["start", "end"]);
 /** Prints a flow run for a person: one line per node as it ends, then a count. Start and End are not listed. */
 export class FlowReporter {
-    constructor({ flow, write, color }) {
+    constructor({ flow, write, color, steps }) {
         this.started = Date.now();
+        this.steps = steps ?? STEP_NODES;
         this.flow = flow;
         this.write = write;
         this.paint = (code, text) => color ? `\u001b[${code}m${text}\u001b[0m` : text;
@@ -28,7 +30,7 @@ export class FlowReporter {
             label = nodeDef(node.kind).label;
         }
         catch {
-            label = node.kind;
+            label = this.steps.find((d) => d.kind === node.kind)?.label ?? node.kind;
         }
         const base = node.title || label;
         const wrote = result.wrote ? Object.keys(result.wrote) : [];

package/dist/cli/flow.d.ts

@@ -1,4 +1,4 @@
 import type { Io } from "./main.js";
-export declare const FLOW_USAGE = "Usage:\n  samurai flow list [--json]                    List the flows in ./flows\n  samurai flow check [<flow>...] [options]      Check flows without running them (all flows when none is given)\n  samurai flow run <flow>... [options]          Run flows, in the order given\n  samurai flow run --all [options]              Run every flow in ./flows, in file name order\n\nA flow is an id (flows/<id>.flow.json) or a path to a .flow.json file.\n\nOptions for check and run:\n  --env <name>                Environment to use (or SAMURAI_ENV)\n  --allow-unsupported         Skip nodes that can't run yet (HTTP request, ...) instead of refusing the flow\n  --json                      Machine-readable output: JSON lines for run, one array for check and list\n\nOptions for run:\n  --timeout <ms>              Time one test may take\n  --expect-timeout <ms>       Time actions and assertions retry\n  --headless, --no-headless   Run the browser without a window, or with one\n  --port <n>                  Browser debugging port (default 9223)\n\nEach run writes result/flows/<id>.json.\nExit code: 0 when every node that should run passed, 1 when a node failed or the run was cancelled,\n2 for a usage, configuration or flow-file error, or a flow that has errors (nothing ran).\n";
+export declare const FLOW_USAGE = "Usage:\n  samurai flow list [--json]                    List the flows in ./flows\n  samurai flow check [<flow>...] [options]      Check flows without running them (all flows when none is given)\n  samurai flow run <flow>... [options]          Run flows, in the order given\n  samurai flow run --all [options]              Run every flow in ./flows, in file name order\n\nA flow is an id (flows/<id>.flow.json) or a path to a .flow.json file.\n\nOptions for check and run:\n  --env <name>                Environment to use (or SAMURAI_ENV)\n  --allow-unsupported         Skip nodes whose kind has no handler instead of refusing the flow (every built-in kind runs)\n  --json                      Machine-readable output: JSON lines for run, one array for check and list\n\nOptions for run:\n  --timeout <ms>              Time one test may take\n  --expect-timeout <ms>       Time actions and assertions retry\n  --headless, --no-headless   Run the browser without a window, or with one\n  --port <n>                  Browser debugging port (default 9223)\n\nEach run writes result/flows/<id>.json.\nExit code: 0 when every node that should run passed, 1 when a node failed or the run was cancelled,\n2 for a usage, configuration or flow-file error, or a flow that has errors (nothing ran).\n";
 /** `samurai flow ...`: `argv` is what follows `flow`. Returns the exit code */
 export declare function flowCommand(argv: string[], io: Io): Promise<number>;

package/dist/cli/flow.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { parseCommandLine, parseRunnerFlags, parseRunOverrides, } from "./args.js";
 import { FlowReporter } from "./flow-reporter.js";
+import { projectSteps } from "../flows/steps/index.js";
 import {} from "../flows/core/index.js";
 import { FLOW_SUFFIX, FlowCheckError, FlowReportBuilder, checkFlowInProject, flowsDir, listFlows, readFlow, readFlowPath, runFlowInProject, writeFlowReport, } from "../flows/run/index.js";
 export const FLOW_USAGE = `Usage:
@@ -13,7 +14,7 @@ A flow is an id (flows/<id>.flow.json) or a path to a .flow.json file.
 
 Options for check and run:
   --env <name>                Environment to use (or SAMURAI_ENV)
-  --allow-unsupported         Skip nodes that can't run yet (HTTP request, ...) instead of refusing the flow
+  --allow-unsupported         Skip nodes whose kind has no handler instead of refusing the flow (every built-in kind runs)
   --json                      Machine-readable output: JSON lines for run, one array for check and list
 
 Options for run:
@@ -136,6 +137,7 @@ async function run(refs, io, options) {
             io.err(`${flow.id} can't run:\n${problemLines(io, described)}Nothing was run.\n`);
         return 2;
     };
+    const { nodes: steps } = await projectSteps({ projectDir });
     // Several flows: refuse them all before the first one runs
     if (flows.length > 1) {
         for (const flow of flows) {
@@ -159,7 +161,7 @@ async function run(refs, io, options) {
         const builder = new FlowReportBuilder(flow);
         const human = options.json
             ? undefined
-            : new FlowReporter({ flow, write: io.out, color: io.color });
+            : new FlowReporter({ flow, write: io.out, color: io.color, steps });
         if (flows.indexOf(flow) > 0 && !options.json)
             io.out("\n");
         let summary;

package/dist/config/config.d.ts

@@ -19,6 +19,11 @@ export declare function projectDir(): string;
 export declare function browsersDir(): string;
 /** The whole `samurai.config.ts` of the project (the working directory unless a project is active) */
 export declare function loadConfig(): Promise<SamuraiTestConfig>;
+/** A project's config without keeping the project active (`withProject` is one at a time): the given one, else its samurai.config.ts */
+export declare function projectConfig(options: {
+    projectDir?: string;
+    config?: SamuraiTestConfig;
+}): Promise<SamuraiTestConfig>;
 export declare function readConfig<K extends keyof SamuraiTestConfig>(key: K): Promise<SamuraiTestConfig[K]>;
 export declare function defineConfig(config: SamuraiTestConfig): SamuraiTestConfig;
 export {};

package/dist/config/config.js

@@ -32,6 +32,19 @@ export async function loadConfig() {
     }
     return config.default;
 }
+/** A project's config without keeping the project active (`withProject` is one at a time): the given one, else its samurai.config.ts */
+export async function projectConfig(options) {
+    if (options.config)
+        return options.config;
+    const previous = activeProject;
+    setActiveProject({ dir: path.resolve(options.projectDir ?? process.cwd()) });
+    try {
+        return await loadConfig();
+    }
+    finally {
+        setActiveProject(previous);
+    }
+}
 export async function readConfig(key) {
     const value = (await loadConfig())[key];
     logger.debug("Resolved config value: ", { value });

package/dist/flows/core/check.d.ts

@@ -1,4 +1,5 @@
 import { type FlowProblem } from "./nodes/index.js";
+import type { AnyNodeDefinition } from "./nodes/define.js";
 import type { FlowFile, FlowNodeModel } from "./schema.js";
 export type { FlowProblem } from "./nodes/index.js";
 export interface CheckOptions {
@@ -27,6 +28,8 @@ export interface CheckOptions {
      * The SAMURAI app passes the editor's titles (a Test node shows its test's name).
      */
     titles?: (node: FlowNodeModel) => string | undefined;
+    /** Definitions of kinds core doesn't have (steps). A node of a kind in neither is "Unknown step". */
+    nodes?: readonly AnyNodeDefinition[];
 }
 /**
  * Checks a flow before a run: the shape of the graph, keys, references that still
@@ -39,4 +42,4 @@ export declare function checkFlow(flow: FlowFile, options?: CheckOptions): FlowP
 export declare function expressionProblems(flow: FlowFile, environment: {
     name: string;
     variables: Record<string, unknown>;
-}): FlowProblem[];
+}, nodes?: readonly AnyNodeDefinition[]): FlowProblem[];

package/dist/flows/core/check.js

@@ -3,14 +3,15 @@ import { KEY_PATTERN } from "./keys.js";
 import { branchNames, dynamicOf, getPath, nodeDef, withDefaults, } from "./nodes/index.js";
 /** What the node is called in a message: its title, else its key, else its kind's label */
 const titleOf = (node, def) => node.title || node.key || def?.label || node.kind;
-const defOf = (kind) => {
-    try {
-        return nodeDef(kind);
-    }
-    catch {
-        return undefined;
-    }
-};
+const definitions = (nodes = []) => (kind) => nodes.find((d) => d.kind === kind) ??
+    (() => {
+        try {
+            return nodeDef(kind);
+        }
+        catch {
+            return undefined;
+        }
+    })();
 /** Node ids in the order a run reaches them: from Start, following edges */
 function reachableFrom(flow, startId) {
     const out = new Map();
@@ -36,6 +37,7 @@ function reachableFrom(flow, startId) {
  * its key, else its kind's label (the app names it by what the editor shows).
  */
 export function checkFlow(flow, options = {}) {
+    const defOf = definitions(options.nodes);
     const problems = [];
     const tests = options.tests ? new Set(options.tests) : undefined;
     const groups = options.groups ? new Set(options.groups) : undefined;
@@ -45,7 +47,7 @@ export function checkFlow(flow, options = {}) {
             problems.push({
                 level: "error",
                 nodeId: n.id,
-                message: `Unknown node kind: ${n.kind}`,
+                message: `Unknown step: ${n.kind}`,
             });
     const starts = flow.nodes.filter((n) => shapeOf(n) === "start");
     const ends = flow.nodes.filter((n) => shapeOf(n) === "end");
@@ -138,9 +140,9 @@ export function checkFlow(flow, options = {}) {
         else
             seen.set(n.key, n.id);
     }
-    problems.push(...emptyExpressions(flow));
+    problems.push(...emptyExpressions(flow, defOf));
     if (options.environment)
-        problems.push(...expressionProblems(flow, options.environment));
+        problems.push(...expressionProblems(flow, options.environment, options.nodes));
     const nodeCount = flow.nodes.filter((n) => {
         const s = shapeOf(n);
         return s !== "start" && s !== "end";
@@ -157,7 +159,7 @@ export function checkFlow(flow, options = {}) {
     return problems;
 }
 /** Every expression field left empty: it would stop the run at its node */
-function emptyExpressions(flow) {
+function emptyExpressions(flow, defOf) {
     return flow.nodes.flatMap((n) => {
         const def = defOf(n.kind);
         if (!def)
@@ -176,7 +178,8 @@ function emptyExpressions(flow) {
     });
 }
 /** Every expression field that doesn't check out, as "Label: message" */
-export function expressionProblems(flow, environment) {
+export function expressionProblems(flow, environment, nodes = []) {
+    const defOf = definitions(nodes);
     return flow.nodes.flatMap((n) => {
         const def = defOf(n.kind);
         if (!def)
@@ -187,7 +190,7 @@ export function expressionProblems(flow, environment) {
             const text = getPath(n, f.path);
             if (typeof text !== "string" || text.trim() === "")
                 return [];
-            const problem = problemOf(text, scopeAt(flow, n.id, environment));
+            const problem = problemOf(text, scopeAt(flow, n.id, environment, nodes));
             return problem
                 ? [
                     {

package/dist/flows/core/expression/check.d.ts

@@ -1,5 +1,7 @@
 import { type ExpressionError, type Parsed } from "./parse.js";
 export interface ExpressionScope {
+    /** Output names of the nodes that have them, by key */
+    outputs?: Record<string, readonly string[]>;
     /** The flow environment's name and its variable names */
     env: {
         name: string;

package/dist/flows/core/expression/check.js

@@ -81,10 +81,10 @@ export function checkExpression(parsed, scope) {
                     message: `${name} is on another branch, so it has no result here`,
                     at,
                 };
-            if (field !== undefined &&
-                !NODE_FIELDS.includes(field))
+            const fields = [...NODE_FIELDS, ...(scope.outputs?.[name] ?? [])];
+            if (field !== undefined && !fields.includes(field))
                 return {
-                    message: `nodes.${name}.${field} doesn't exist. Use ${list(NODE_FIELDS)}`,
+                    message: `nodes.${name}.${field} doesn't exist. Use ${list(fields)}`,
                     at,
                 };
         }

package/dist/flows/core/expression/evaluate.d.ts

@@ -6,7 +6,7 @@ export interface ExpressionContext {
         status: string;
         durationMs?: number;
         error?: string;
-    }>;
+    } & Record<string, unknown>>;
     run: {
         environment: string;
         trigger: string;

package/dist/flows/core/expression/scope.d.ts

@@ -1,7 +1,8 @@
+import type { AnyNodeDefinition } from "../nodes/define.js";
 import type { FlowFile } from "../schema.js";
 import type { ExpressionScope } from "./check.js";
-/** What an expression at `nodeId` may use */
+/** What an expression at `nodeId` may use; `nodes` adds definitions core doesn't have (steps) */
 export declare function scopeAt(flow: FlowFile, nodeId: string, environment: {
     name: string;
     variables: Record<string, unknown>;
-}): ExpressionScope;
+}, nodes?: readonly AnyNodeDefinition[]): ExpressionScope;

package/dist/flows/core/expression/scope.js

@@ -1,17 +1,25 @@
 import { ancestors, dominates, reachOrder } from "../graph.js";
-/** What an expression at `nodeId` may use */
-export function scopeAt(flow, nodeId, environment) {
+import { NODES } from "../nodes/index.js";
+import { getPath } from "../nodes/path.js";
+/** What an expression at `nodeId` may use; `nodes` adds definitions core doesn't have (steps) */
+export function scopeAt(flow, nodeId, environment, nodes = []) {
+    const defOf = (kind) => nodes.find((d) => d.kind === kind) ?? NODES.find((d) => d.kind === kind);
     const keyOf = (id) => flow.nodes.find((n) => n.id === id)?.key;
     const keys = (ids) => [...ids].map(keyOf).filter((k) => !!k);
     const before = ancestors(flow, nodeId);
     const after = new Set(reachOrder(flow, nodeId));
     after.delete(nodeId);
     const vars = flow.nodes
-        .filter((n) => n.kind === "set-variable" &&
-        n.id !== nodeId &&
-        dominates(flow, n.id, nodeId))
-        .map((n) => n.config?.name)
+        .filter((n) => n.id !== nodeId && dominates(flow, n.id, nodeId))
+        .map((n) => {
+        const path = defOf(n.kind)?.writesVar;
+        return path ? getPath(n, path) : undefined;
+    })
         .filter((name) => typeof name === "string" && name !== "");
+    const outputs = Object.fromEntries(flow.nodes.flatMap((n) => {
+        const results = defOf(n.kind)?.results;
+        return n.key && results?.length ? [[n.key, results]] : [];
+    }));
     return {
         env: {
             name: environment.name,
@@ -21,5 +29,6 @@ export function scopeAt(flow, nodeId, environment) {
         before: keys(before),
         after: keys(after),
         all: keys(flow.nodes.map((n) => n.id)),
+        outputs,
     };
 }

package/dist/flows/core/index.d.ts

@@ -8,9 +8,10 @@ export * from "./graph.js";
 export * from "./expression/index.js";
 export * from "./nodes/index.js";
 export * from "./check.js";
+export * from "./steps.js";
 /**
  * Version of the contract between the SAMURAI app and this framework.
  * Increments whenever the app and the framework must agree on something new
  * (a node kind, a field, an event), so the app can tell when the framework is too old.
  */
-export declare const FLOWS_API = 1;
+export declare const FLOWS_API = 2;

package/dist/flows/core/index.js

@@ -8,9 +8,10 @@ export * from "./graph.js";
 export * from "./expression/index.js";
 export * from "./nodes/index.js";
 export * from "./check.js";
+export * from "./steps.js";
 /**
  * Version of the contract between the SAMURAI app and this framework.
  * Increments whenever the app and the framework must agree on something new
  * (a node kind, a field, an event), so the app can tell when the framework is too old.
  */
-export const FLOWS_API = 1;
+export const FLOWS_API = 2;

package/dist/flows/core/nodes/define.d.ts

@@ -110,6 +110,10 @@ export interface NodeCoreDefinition<K extends string = string, C = Record<string
     fields: readonly Field[];
     /** The node can write outputs (shared-context variables) */
     outputs?: boolean;
+    /** A step's output names: readable later as `nodes.<key>.<name>` */
+    results?: readonly string[];
+    /** The path of the field holding the name of a variable the node writes (`vars.<name>`) */
+    writesVar?: string;
     /** The node has an "on failure" choice */
     onFailure?: boolean;
     /** Pure: problems with this node alone. `node.config` has the field defaults filled in. */

package/dist/flows/core/nodes/index.d.ts

@@ -9,70 +9,14 @@ declare const registered: readonly [import("./define.js").NodeCoreDefinition<"st
     readonly label: "Expression";
     readonly placeholder: "nodes.login.status == \"passed\"";
     readonly default: "";
-}]>>, import("./define.js").NodeCoreDefinition<"parallel", import("./define.js").ConfigOf<readonly []>>, import("./define.js").NodeCoreDefinition<"wait", import("./define.js").ConfigOf<readonly [{
-    readonly path: "title";
-    readonly type: "text";
-    readonly label: "Title";
-}, {
-    readonly path: "subtitle";
-    readonly type: "text";
-    readonly label: "Description";
-}, {
-    readonly path: "config.ms";
-    readonly type: "number";
-    readonly label: "Duration";
-    readonly unit: "ms";
-    readonly default: 1000;
-}]>>, import("./define.js").NodeCoreDefinition<"set-variable", import("./define.js").ConfigOf<readonly [{
-    readonly path: "config.name";
-    readonly type: "text";
-    readonly label: "Name";
-    readonly placeholder: "orderId";
-    readonly default: "";
-}, {
-    readonly path: "config.value";
-    readonly type: "expression";
-    readonly label: "Value";
-    readonly placeholder: "\"order-\" + run.environment";
-    readonly default: "";
-}]>>, import("./define.js").NodeCoreDefinition<"api", import("./define.js").ConfigOf<readonly [{
-    readonly path: "title";
-    readonly type: "text";
-    readonly label: "Title";
-}, {
-    readonly path: "subtitle";
-    readonly type: "text";
-    readonly label: "Description";
-}]>>, import("./define.js").NodeCoreDefinition<"database", import("./define.js").ConfigOf<readonly [{
-    readonly path: "title";
-    readonly type: "text";
-    readonly label: "Title";
-}, {
-    readonly path: "subtitle";
-    readonly type: "text";
-    readonly label: "Description";
-}]>>, import("./define.js").NodeCoreDefinition<"email", import("./define.js").ConfigOf<readonly [{
-    readonly path: "title";
-    readonly type: "text";
-    readonly label: "Title";
-}, {
-    readonly path: "subtitle";
-    readonly type: "text";
-    readonly label: "Description";
-}]>>, import("./define.js").NodeCoreDefinition<"script", import("./define.js").ConfigOf<readonly [{
-    readonly path: "title";
-    readonly type: "text";
-    readonly label: "Title";
-}, {
-    readonly path: "subtitle";
-    readonly type: "text";
-    readonly label: "Description";
-}]>>];
+}]>>, import("./define.js").NodeCoreDefinition<"parallel", import("./define.js").ConfigOf<readonly []>>];
 export type NodeKind = (typeof registered)[number]["kind"];
 export declare const NODES: readonly AnyNodeDefinition[];
 /** The definition of a kind; throws for an unknown one */
 export declare function nodeDef(kind: string): AnyNodeDefinition;
-/** How a run treats a node in the graph */
+/** The kinds core defines itself; every other kind is a step */
+export declare const CLOSED_KINDS: readonly string[];
+/** How a run treats a node in the graph: a kind core doesn't define is a step */
 export declare const shapeOf: (node: {
     kind: string;
 }) => import("./define.js").Shape;
@@ -97,11 +41,5 @@ export declare const branchOf: (node: {
 export declare const branchNames: (node: {
     kind: string;
 }) => string[];
-/**
- * Kinds defined in core that a run has no handler for yet (`flows/run` skips or refuses
- * them). The one list: `flows/run` uses it too, and the builder warns with it without
- * importing `flows/run`.
- */
-export declare const UNSUPPORTED_KINDS: readonly string[];
 export * from "./define.js";
 export * from "./path.js";

package/dist/flows/core/nodes/index.js

@@ -1,30 +1,11 @@
-import { api } from "./api.js";
 import { condition } from "./condition.js";
-import { database } from "./database.js";
-import { email } from "./email.js";
 import { end } from "./end.js";
 import { group } from "./group.js";
 import { parallel } from "./parallel.js";
-import { script } from "./script.js";
-import { setVariable } from "./set-variable.js";
 import { start } from "./start.js";
 import { test } from "./test.js";
-import { wait } from "./wait.js";
-// Library order
-const registered = [
-    start,
-    end,
-    test,
-    group,
-    condition,
-    parallel,
-    wait,
-    setVariable,
-    api,
-    database,
-    email,
-    script,
-];
+// Library order. Every other kind is a step (`flows/steps`).
+const registered = [start, end, test, group, condition, parallel];
 export const NODES = registered;
 /** The definition of a kind; throws for an unknown one */
 export function nodeDef(kind) {
@@ -33,14 +14,18 @@ export function nodeDef(kind) {
         throw new Error(`Unknown node kind: ${kind}`);
     return def;
 }
-/** How a run treats a node in the graph */
-export const shapeOf = (node) => nodeDef(node.kind).shape;
+/** The definition of a kind core registers; undefined for any other (a step) */
+const closedDef = (kind) => NODES.find((d) => d.kind === kind);
+/** The kinds core defines itself; every other kind is a step */
+export const CLOSED_KINDS = NODES.map((d) => d.kind);
+/** How a run treats a node in the graph: a kind core doesn't define is a step */
+export const shapeOf = (node) => closedDef(node.kind)?.shape ?? "step";
 /** The branch names a dynamic list gives its branches: branch-0, branch-1, ... */
 export const dynamicName = (index) => `branch-${index}`;
 /** The dynamic branch settings of a `branches` node; undefined for a fixed list and any other shape */
 export const dynamicOf = (node) => {
-    const def = nodeDef(node.kind);
-    return def.shape === "branches" &&
+    const def = closedDef(node.kind);
+    return def?.shape === "branches" &&
         def.branches &&
         !Array.isArray(def.branches)
         ? def.branches
@@ -51,8 +36,8 @@ export const dynamicOf = (node) => {
  * `min` empty ones for a dynamic list. Empty for any other shape.
  */
 export const branchesOf = (node) => {
-    const def = nodeDef(node.kind);
-    if (def.shape !== "branches" || !def.branches)
+    const def = closedDef(node.kind);
+    if (!def || def.shape !== "branches" || !def.branches)
         return [];
     if (Array.isArray(def.branches))
         return def.branches;
@@ -66,16 +51,5 @@ export const branchOf = (node, handle) => dynamicOf(node)
     : branchesOf(node).find((b) => b.name === handle);
 /** The names of the branches `branchesOf` lists */
 export const branchNames = (node) => branchesOf(node).map((b) => b.name);
-/**
- * Kinds defined in core that a run has no handler for yet (`flows/run` skips or refuses
- * them). The one list: `flows/run` uses it too, and the builder warns with it without
- * importing `flows/run`.
- */
-export const UNSUPPORTED_KINDS = [
-    "api",
-    "database",
-    "email",
-    "script",
-];
 export * from "./define.js";
 export * from "./path.js";

package/dist/flows/core/steps.d.ts

@@ -0,0 +1,42 @@
+import type { Field, FlowProblem, NodeCoreDefinition } from "./nodes/define.js";
+import type { FlowNodeModel } from "./schema.js";
+/** Rules a step field carries: checked live in the builder and again by checkFlow */
+export interface FieldRules {
+    required?: boolean;
+    /** `number` fields */
+    min?: number;
+    max?: number;
+    /** `text` fields: a regular expression the value must match */
+    pattern?: string;
+    /** Said instead of the default when `pattern` doesn't match */
+    patternMessage?: string;
+}
+export type StepField = Field & FieldRules;
+export type StepSection = "control" | "integrations";
+export interface StepOutput {
+    name: string;
+    label?: string;
+}
+/** A step as data: what the app's catalog holds. No functions. */
+export interface StepInfo {
+    /** Stored in flow files as the node's `kind` */
+    kind: string;
+    label: string;
+    /** A design-system icon name */
+    icon: string;
+    section: StepSection;
+    /** `config.*` fields; Title and Description are added by `stepNodeOf` */
+    fields: readonly StepField[];
+    /** The line under the title: `{config.x}` is replaced with the field's value */
+    summary?: string;
+    outputs?: readonly StepOutput[];
+    /** The path of the field holding a variable name the step writes */
+    writesVar?: string;
+}
+export declare const STEP_KIND: RegExp;
+/** A node's own result fields: an output can't take these names */
+export declare const RESERVED_OUTPUTS: readonly string[];
+/** Problems with `node`'s values against the fields' rules, as "Label: message" */
+export declare function fieldProblems(fields: readonly StepField[], node: FlowNodeModel, label: string): FlowProblem[];
+/** The definition core's walker and checkFlow use for a step; `validate` is the step's own (engine only) */
+export declare function stepNodeOf(info: StepInfo, validate?: NodeCoreDefinition["validate"]): NodeCoreDefinition;

package/dist/flows/core/steps.js

@@ -0,0 +1,58 @@
+import { getPath } from "./nodes/path.js";
+export const STEP_KIND = /^[a-z][a-z0-9-]*$/;
+/** A node's own result fields: an output can't take these names */
+export const RESERVED_OUTPUTS = [
+    "status",
+    "durationMs",
+    "error",
+];
+const TITLE_FIELDS = [
+    { path: "title", type: "text", label: "Title" },
+    { path: "subtitle", type: "text", label: "Description" },
+];
+const empty = (value) => value === undefined || (typeof value === "string" && value.trim() === "");
+/** Problems with `node`'s values against the fields' rules, as "Label: message" */
+export function fieldProblems(fields, node, label) {
+    const problems = [];
+    const add = (message) => problems.push({
+        level: "error",
+        nodeId: node.id,
+        message: `${label}: ${message}`,
+    });
+    for (const f of fields) {
+        const name = f.label ?? f.path;
+        const value = getPath(node, f.path);
+        if (f.required && empty(value)) {
+            add(`${name} is required.`);
+            continue;
+        }
+        if (typeof value === "number") {
+            if (f.min !== undefined && value < f.min)
+                add(`${name} must be at least ${f.min}.`);
+            if (f.max !== undefined && value > f.max)
+                add(`${name} must be at most ${f.max}.`);
+        }
+        if (f.pattern &&
+            typeof value === "string" &&
+            value !== "" &&
+            !new RegExp(f.pattern).test(value))
+            add(f.patternMessage ?? `${name} doesn't match ${f.pattern}.`);
+    }
+    return problems;
+}
+/** The definition core's walker and checkFlow use for a step; `validate` is the step's own (engine only) */
+export function stepNodeOf(info, validate) {
+    return {
+        kind: info.kind,
+        label: info.label,
+        shape: "step",
+        fields: [...TITLE_FIELDS, ...info.fields],
+        onFailure: true,
+        results: (info.outputs ?? []).map((o) => o.name),
+        ...(info.writesVar !== undefined && { writesVar: info.writesVar }),
+        validate: (node, ctx) => [
+            ...fieldProblems(info.fields, node, ctx.label),
+            ...(validate?.(node, ctx) ?? []),
+        ],
+    };
+}

package/dist/flows/run/events.d.ts

@@ -8,8 +8,10 @@ export interface NodeResult {
     note?: string;
     /** Condition: the branch taken */
     branch?: string;
-    /** Set variable: what it wrote */
+    /** What the node wrote to vars */
     wrote?: Record<string, unknown>;
+    /** A step's outputs, readable later as `nodes.<key>.<name>` */
+    outputs?: Record<string, unknown>;
 }
 /** One test of a node: absolute file and full name */
 export interface NodeTest {

package/dist/flows/run/handlers/index.d.ts

@@ -1,6 +1,4 @@
 import type { Handler } from "./support.js";
 export type { Handler, HandlerRun, Outcome } from "./support.js";
-/** The kinds a run can execute, by kind */
+/** The kinds a run can execute, by kind: the closed ones and every built-in step */
 export declare const HANDLERS: Readonly<Record<string, Handler>>;
-/** Kinds that exist in `flows/core` and have no handler yet (core's one list) */
-export declare const UNSUPPORTED: readonly string[];