@itmetsam/samurai-framework 0.2.2 → 0.3.0

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

@@ -0,0 +1,128 @@
+import type { FlowNodeModel } from "../schema.js";
+/** A problem `checkFlow` or a node's `validate` reports */
+export interface FlowProblem {
+    level: "error" | "warning";
+    message: string;
+    nodeId?: string;
+}
+/** What a node's `validate` can read besides the node itself */
+export interface NodeCtx {
+    /** The definition's `label`: the one place a node's name is written */
+    label: string;
+    /** The test ids that exist; undefined when checkFlow was not given them (no reference check) */
+    tests?: ReadonlySet<string>;
+    /** The group names that exist; undefined when checkFlow was not given them */
+    groups?: ReadonlySet<string>;
+}
+export interface Option {
+    label: string;
+    value: string;
+}
+interface FieldBase {
+    /** Where the value lives in the node: `title`, `subtitle`, `continueSession`, `config.<key>`, `ref.testId` or `ref.group` */
+    path: string;
+    label?: string;
+}
+/**
+ * One setting of a node, as data. The editor decides how to render it. The app's
+ * `custom` field type (a React component) is not part of core: the editor attaches
+ * those to a kind itself.
+ */
+export type Field = (FieldBase & {
+    type: "text";
+    placeholder?: string;
+    default?: string;
+}) | (FieldBase & {
+    type: "code";
+    placeholder?: string;
+    default?: string;
+}) | (FieldBase & {
+    type: "expression";
+    placeholder?: string;
+    default?: string;
+}) | (FieldBase & {
+    type: "number";
+    unit?: string;
+    default?: number;
+}) | (FieldBase & {
+    type: "select";
+    options: Option[];
+    default?: string;
+}) | (FieldBase & {
+    type: "segmented";
+    options: Option[];
+    default?: string;
+}) | (FieldBase & {
+    type: "switch";
+    default?: boolean;
+}) | (FieldBase & {
+    type: "test";
+}) | (FieldBase & {
+    type: "group";
+});
+/** How a run treats a node in the graph */
+export type Shape = "start" | "end" | "step" | "branches";
+/** The tones of the design system's flow chips */
+export type BranchTone = "neutral" | "success" | "warning" | "error" | "info";
+/** One named way out of a `branches` node */
+export interface Branch {
+    /** Stored as the edge's `sourceHandle` */
+    name: string;
+    /** The chip on the canvas; leave it out for no chip */
+    label?: string;
+    /** The chip's colour: a theme tone, or any CSS colour such as "#7c3aed" */
+    color?: BranchTone | (string & {});
+}
+/** Branches that come and go: filled ones plus one empty to drop onto, at least `min` in all */
+export interface DynamicBranches {
+    dynamic: true;
+    min: number;
+}
+/** The type a field's value has in `config` */
+type ValueOf<F> = F extends {
+    type: "number";
+} ? number : F extends {
+    type: "switch";
+} ? boolean : string;
+/** `config` as the definition's `config.*` fields describe it */
+export type ConfigOf<F extends readonly Field[]> = {
+    [K in F[number] as K["path"] extends `config.${infer P}` ? P : never]: ValueOf<K>;
+};
+/** A node whose `config` is typed (and filled from the field defaults) */
+export type TypedNode<C> = Omit<FlowNodeModel, "config"> & {
+    config: C;
+};
+/**
+ * The core half of a node kind: data and pure functions only. What a kind does in a
+ * run is a handler in `flows/run`; how it looks is the editor's half.
+ */
+export interface NodeCoreDefinition<K extends string = string, C = Record<string, unknown>> {
+    /** Stored in flow files as the node's `kind` */
+    kind: K;
+    /** The kind's name; messages use it */
+    label: string;
+    shape: Shape;
+    /**
+     * `branches`: a fixed list (the first is the one kept on delete), or
+     * `{ dynamic: true, min }` for a list that grows as branches are filled, named `branch-<n>`
+     */
+    branches?: readonly Branch[] | DynamicBranches;
+    fields: readonly Field[];
+    /** The node can write outputs (shared-context variables) */
+    outputs?: boolean;
+    /** The node has an "on failure" choice */
+    onFailure?: boolean;
+    /** Pure: problems with this node alone. `node.config` has the field defaults filled in. */
+    validate?: (node: TypedNode<C>, ctx: NodeCtx) => FlowProblem[];
+}
+/** Any definition, for the registry */
+export type AnyNodeDefinition = NodeCoreDefinition<string, any>;
+/** Declares a node kind; the type of `config` comes from the `config.*` fields */
+export declare function defineNode<const K extends string, const F extends readonly Field[]>(def: Omit<NodeCoreDefinition<K, ConfigOf<F>>, "fields"> & {
+    fields: F;
+}): NodeCoreDefinition<K, ConfigOf<F>>;
+/** The values the definition's `config.*` fields start with */
+export declare function configDefaults(def: Pick<AnyNodeDefinition, "fields">): Record<string, unknown>;
+/** The node with every field default filled in, so `validate` sees typed config even for old files */
+export declare function withDefaults<C>(def: NodeCoreDefinition<string, C>, node: FlowNodeModel): TypedNode<C>;
+export {};

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

@@ -0,0 +1,21 @@
+/** Declares a node kind; the type of `config` comes from the `config.*` fields */
+export function defineNode(def) {
+    return def;
+}
+/** The values the definition's `config.*` fields start with */
+export function configDefaults(def) {
+    const config = {};
+    for (const f of def.fields)
+        if (f.path.startsWith("config.") &&
+            "default" in f &&
+            f.default !== undefined)
+            config[f.path.slice("config.".length)] = f.default;
+    return config;
+}
+/** The node with every field default filled in, so `validate` sees typed config even for old files */
+export function withDefaults(def, node) {
+    return {
+        ...node,
+        config: { ...configDefaults(def), ...node.config },
+    };
+}

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

@@ -0,0 +1,9 @@
+export declare const email: 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";
+}]>>;

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

@@ -0,0 +1,12 @@
+import { defineNode } from "./define.js";
+// Declared so flows can hold it; no handler runs it yet (unsupported).
+export const email = defineNode({
+    kind: "email",
+    label: "Email inbox",
+    shape: "step",
+    fields: [
+        { path: "title", type: "text", label: "Title" },
+        { path: "subtitle", type: "text", label: "Description" },
+    ],
+    outputs: true,
+});

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

@@ -0,0 +1 @@
+export declare const end: import("./define.js").NodeCoreDefinition<"end", import("./define.js").ConfigOf<readonly []>>;

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

@@ -0,0 +1,7 @@
+import { defineNode } from "./define.js";
+export const end = defineNode({
+    kind: "end",
+    label: "End",
+    shape: "end",
+    fields: [],
+});

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

@@ -0,0 +1,5 @@
+export declare const group: import("./define.js").NodeCoreDefinition<"group", import("./define.js").ConfigOf<readonly [{
+    readonly path: "ref.group";
+    readonly type: "group";
+    readonly label: "Group";
+}]>>;

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

@@ -0,0 +1,18 @@
+import { defineNode } from "./define.js";
+// The app's editor adds the `continueSession` field (a custom component) to this kind.
+export const group = defineNode({
+    kind: "group",
+    label: "Group",
+    shape: "step",
+    fields: [{ path: "ref.group", type: "group", label: "Group" }],
+    outputs: true,
+    validate: (node, ctx) => ctx.groups && !(node.ref?.group && ctx.groups.has(node.ref.group))
+        ? [
+            {
+                level: "error",
+                nodeId: node.id,
+                message: `The ${ctx.label.toLowerCase()} ${node.ref?.group ?? ""} no longer exists.`,
+            },
+        ]
+        : [],
+});

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

@@ -0,0 +1,107 @@
+import type { AnyNodeDefinition, Branch, DynamicBranches } from "./define.js";
+declare const registered: readonly [import("./define.js").NodeCoreDefinition<"start", import("./define.js").ConfigOf<readonly []>>, import("./define.js").NodeCoreDefinition<"end", import("./define.js").ConfigOf<readonly []>>, import("./define.js").NodeCoreDefinition<"test", import("./define.js").ConfigOf<readonly []>>, import("./define.js").NodeCoreDefinition<"group", import("./define.js").ConfigOf<readonly [{
+    readonly path: "ref.group";
+    readonly type: "group";
+    readonly label: "Group";
+}]>>, import("./define.js").NodeCoreDefinition<"condition", import("./define.js").ConfigOf<readonly [{
+    readonly path: "config.expr";
+    readonly type: "expression";
+    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";
+}]>>];
+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 */
+export declare const shapeOf: (node: {
+    kind: string;
+}) => import("./define.js").Shape;
+/** The branch names a dynamic list gives its branches: branch-0, branch-1, ... */
+export declare const dynamicName: (index: number) => string;
+/** The dynamic branch settings of a `branches` node; undefined for a fixed list and any other shape */
+export declare const dynamicOf: (node: {
+    kind: string;
+}) => DynamicBranches | undefined;
+/**
+ * The branches a new `branches` node starts with, in order: its fixed list, or
+ * `min` empty ones for a dynamic list. Empty for any other shape.
+ */
+export declare const branchesOf: (node: {
+    kind: string;
+}) => readonly Branch[];
+/** The branch an edge out of a `branches` node leaves by (a dynamic list has no labels or colours) */
+export declare const branchOf: (node: {
+    kind: string;
+}, handle: string | undefined) => Branch | undefined;
+/** The names of the branches `branchesOf` lists */
+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

@@ -0,0 +1,81 @@
+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,
+];
+export const NODES = registered;
+/** The definition of a kind; throws for an unknown one */
+export function nodeDef(kind) {
+    const def = NODES.find((d) => d.kind === kind);
+    if (!def)
+        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 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" &&
+        def.branches &&
+        !Array.isArray(def.branches)
+        ? def.branches
+        : undefined;
+};
+/**
+ * The branches a new `branches` node starts with, in order: its fixed list, or
+ * `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)
+        return [];
+    if (Array.isArray(def.branches))
+        return def.branches;
+    return Array.from({ length: def.branches.min }, (_, i) => ({ name: dynamicName(i) }));
+};
+/** The branch an edge out of a `branches` node leaves by (a dynamic list has no labels or colours) */
+export const branchOf = (node, handle) => dynamicOf(node)
+    ? handle
+        ? { name: handle }
+        : undefined
+    : 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/nodes/parallel.d.ts

@@ -0,0 +1 @@
+export declare const parallel: import("./define.js").NodeCoreDefinition<"parallel", import("./define.js").ConfigOf<readonly []>>;

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

@@ -0,0 +1,11 @@
+import { defineNode } from "./define.js";
+// Every branch leads on to the node after the Parallel. Branches are dropped
+// onto one at a time: the list is always its filled branches plus one empty.
+export const parallel = defineNode({
+    kind: "parallel",
+    label: "Parallel",
+    shape: "branches",
+    branches: { dynamic: true, min: 2 },
+    fields: [],
+    onFailure: true,
+});

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

@@ -0,0 +1,5 @@
+import type { FlowNodeModel } from "../schema.js";
+/** Reads a field's value from the node: `title`, `subtitle`, `continueSession`, `config.*` or `ref.*` */
+export declare function getPath(node: FlowNodeModel, path: string): unknown;
+/** The patch that writes a field's value, keeping the other keys of `config` and `ref` */
+export declare function setPath(node: FlowNodeModel, path: string, value: unknown): Partial<FlowNodeModel>;

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

@@ -0,0 +1,21 @@
+/** Splits `config.expr` into `["config", "expr"]`; `title` is a top-level key */
+function split(path) {
+    const i = path.indexOf(".");
+    return i < 0 ? [path, undefined] : [path.slice(0, i), path.slice(i + 1)];
+}
+/** Reads a field's value from the node: `title`, `subtitle`, `continueSession`, `config.*` or `ref.*` */
+export function getPath(node, path) {
+    const [head, rest] = split(path);
+    const top = node[head];
+    if (rest === undefined)
+        return top;
+    return top?.[rest];
+}
+/** The patch that writes a field's value, keeping the other keys of `config` and `ref` */
+export function setPath(node, path, value) {
+    const [head, rest] = split(path);
+    if (rest === undefined)
+        return { [head]: value };
+    const top = node[head];
+    return { [head]: { ...top, [rest]: value } };
+}

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

@@ -0,0 +1,9 @@
+export declare const script: 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";
+}]>>;

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

@@ -0,0 +1,12 @@
+import { defineNode } from "./define.js";
+// Declared so flows can hold it; no handler runs it yet (unsupported).
+export const script = defineNode({
+    kind: "script",
+    label: "Script",
+    shape: "step",
+    fields: [
+        { path: "title", type: "text", label: "Title" },
+        { path: "subtitle", type: "text", label: "Description" },
+    ],
+    outputs: true,
+});

package/dist/flows/core/nodes/set-variable.d.ts

@@ -0,0 +1,13 @@
+export declare const setVariable: 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: "";
+}]>>;

package/dist/flows/core/nodes/set-variable.js

@@ -0,0 +1,39 @@
+import { defineNode } from "./define.js";
+export const setVariable = defineNode({
+    kind: "set-variable",
+    label: "Set variable",
+    shape: "step",
+    fields: [
+        {
+            path: "config.name",
+            type: "text",
+            label: "Name",
+            placeholder: "orderId",
+            default: "",
+        },
+        {
+            path: "config.value",
+            type: "expression",
+            label: "Value",
+            placeholder: '"order-" + run.environment',
+            default: "",
+        },
+    ],
+    validate: (node, ctx) => node.config.name === ""
+        ? [
+            {
+                level: "error",
+                nodeId: node.id,
+                message: `${ctx.label}: give the variable a name.`,
+            },
+        ]
+        : /^[a-z][a-z0-9_]*$/.test(node.config.name)
+            ? []
+            : [
+                {
+                    level: "error",
+                    nodeId: node.id,
+                    message: `${ctx.label}: use lowercase letters, digits and _ for the name.`,
+                },
+            ],
+});

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

@@ -0,0 +1 @@
+export declare const start: import("./define.js").NodeCoreDefinition<"start", import("./define.js").ConfigOf<readonly []>>;

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

@@ -0,0 +1,7 @@
+import { defineNode } from "./define.js";
+export const start = defineNode({
+    kind: "start",
+    label: "Start",
+    shape: "start",
+    fields: [],
+});

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

@@ -0,0 +1 @@
+export declare const test: import("./define.js").NodeCoreDefinition<"test", import("./define.js").ConfigOf<readonly []>>;

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

@@ -0,0 +1,18 @@
+import { defineNode } from "./define.js";
+// The app's editor adds the `continueSession` field (a custom component) to this kind.
+export const test = defineNode({
+    kind: "test",
+    label: "Test",
+    shape: "step",
+    fields: [],
+    outputs: true,
+    validate: (node, ctx) => ctx.tests && !(node.ref?.testId && ctx.tests.has(node.ref.testId))
+        ? [
+            {
+                level: "error",
+                nodeId: node.id,
+                message: `A ${ctx.label.toLowerCase()} in this flow was deleted or moved.`,
+            },
+        ]
+        : [],
+});

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

@@ -0,0 +1,15 @@
+export declare const wait: 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;
+}]>>;

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

@@ -0,0 +1,18 @@
+import { defineNode } from "./define.js";
+export const wait = defineNode({
+    kind: "wait",
+    label: "Wait",
+    shape: "step",
+    fields: [
+        { path: "title", type: "text", label: "Title" },
+        { path: "subtitle", type: "text", label: "Description" },
+        {
+            path: "config.ms",
+            type: "number",
+            label: "Duration",
+            unit: "ms",
+            default: 1000,
+        },
+    ],
+    outputs: true,
+});

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

@@ -0,0 +1,55 @@
+export interface FlowNodeOutput {
+    /** Name of the shared-context variable the node writes */
+    name: string;
+}
+export interface FlowNodeModel {
+    id: string;
+    /** Short name expressions use: nodes.<key>. Lowercase letters, digits and _, unique in the flow */
+    key?: string;
+    /** A registered node kind (see the renderer's node definitions) */
+    kind: string;
+    title?: string;
+    subtitle?: string;
+    /** test: the project test id (file::name). group: the group name */
+    ref?: {
+        testId?: string;
+        group?: string;
+    };
+    outputs?: FlowNodeOutput[];
+    /** What to do when the node fails; "stop" ends the run there */
+    onFailure: "stop" | "continue";
+    /** Continue in the previous node's browser session (kept in the file; the framework opens a fresh browser per test today) */
+    continueSession?: boolean;
+    /** Per-kind settings, named by each definition's `config.*` fields*/
+    config?: Record<string, unknown>;
+    position: {
+        x: number;
+        y: number;
+    };
+}
+export interface FlowEdgeModel {
+    id: string;
+    source: string;
+    target: string;
+    /** The named branch of a node with branches (a condition's "true" or "false", a parallel's "branch-0") */
+    sourceHandle?: string;
+}
+/** One flow, as stored in <project>/flows/<id>.flow.json */
+export interface FlowFile {
+    id: string;
+    /** The file format version; a missing one means 1. See readFlowFile */
+    version?: number;
+    name: string;
+    description?: string;
+    /** The environment the flow runs in; the header's selection otherwise */
+    envDefault?: string;
+    nodes: FlowNodeModel[];
+    edges: FlowEdgeModel[];
+}
+/** The flow file format version this framework writes and reads */
+export declare const FLOW_VERSION = 1;
+/**
+ * Read a parsed flow file (JSON.parse output) into a FlowFile.
+ * A missing `version` is 1; older files are migrated; a file from a newer SAMURAI throws.
+ */
+export declare function readFlowFile(raw: unknown): FlowFile;