@object-ui/app-shell 6.2.3 → 7.1.0

package/dist/views/metadata-admin/previews/screen-spec.js

@@ -0,0 +1,108 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+import { evalCondition } from './simulator/flow-sim-validate';
+/**
+ * Interpolate `{var}` references, mirroring the simulator's `{var}` syntax
+ * (flow-simulator.ts). Known vars are substituted; unknown refs stay literal so
+ * the author still sees the dependency in the design preview.
+ */
+export function interpolate(text, vars) {
+    if (!text)
+        return '';
+    if (!vars)
+        return text;
+    return text.replace(/\{([^{}]+)\}/g, (m, k) => {
+        const v = vars[String(k).trim()];
+        return v === undefined || v === null ? m : String(v);
+    });
+}
+/**
+ * A field's `visibleWhen` gate, evaluated against the current variables using
+ * the SAME evaluator the simulator uses for edge conditions (so the preview
+ * agrees with the simulator). Real metadata mixes `{var}` and bare-var styles
+ * (e.g. `{createOpportunity} == true`, `stage == "review"`), so brace
+ * placeholders are normalised to bare identifiers first.
+ *
+ * Fail-OPEN: a missing condition, an unparseable one, or one that references a
+ * not-yet-set variable (the inspector has no run state) keeps the field
+ * visible — the design preview never hides a configured field just because it
+ * lacks the data to decide. With live run state (the simulator) it gates
+ * faithfully: `createOpportunity == false` hides the field.
+ */
+export function isFieldVisibleWhen(visibleWhen, variables) {
+    if (typeof visibleWhen !== 'string' || !visibleWhen.trim())
+        return true;
+    if (!variables)
+        return true;
+    const normalized = visibleWhen.replace(/\{([\w.]+)\}/g, '$1');
+    const { result, error } = evalCondition(normalized, variables);
+    return error ? true : result;
+}
+/**
+ * Coerce the authored `config.fields` rows into runtime `ScreenFieldSpec`s,
+ * dropping any whose `visibleWhen` evaluates false against `variables` — exactly
+ * what the runtime `screen` executor emits (it filters server-side before
+ * sending the ScreenSpec).
+ */
+function toScreenFields(raw, variables) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const f of raw) {
+        if (!f || typeof f !== 'object')
+            continue;
+        const row = f;
+        if (typeof row.name !== 'string' || !row.name)
+            continue;
+        if (!isFieldVisibleWhen(row.visibleWhen, variables))
+            continue;
+        out.push({
+            name: row.name,
+            label: typeof row.label === 'string' ? row.label : undefined,
+            type: typeof row.type === 'string' ? row.type : undefined,
+            required: row.required === true,
+        });
+    }
+    return out;
+}
+/** Count of authored field rows hidden by their `visibleWhen` against `variables`. */
+export function hiddenFieldCount(node, variables) {
+    const raw = node.config?.fields;
+    if (!Array.isArray(raw))
+        return 0;
+    let hidden = 0;
+    for (const f of raw) {
+        if (!f || typeof f !== 'object')
+            continue;
+        const row = f;
+        if (typeof row.name !== 'string' || !row.name)
+            continue;
+        if (!isFieldVisibleWhen(row.visibleWhen, variables))
+            hidden++;
+    }
+    return hidden;
+}
+/**
+ * Map a screen node's authored `config` onto the runtime `ScreenSpec` — the
+ * same keys the engine's `screen` executor reads (title / description / fields
+ * / objectName / mode / defaults / idVariable). `fields` are gated by their
+ * `visibleWhen` against `variables` (omit `variables` to keep every field).
+ */
+export function buildScreenSpec(node, variables) {
+    const c = (node.config && typeof node.config === 'object' ? node.config : {});
+    const objectName = typeof c.objectName === 'string' && c.objectName ? c.objectName : undefined;
+    const mode = c.mode === 'edit' ? 'edit' : c.mode === 'create' ? 'create' : undefined;
+    const defaults = c.defaults && typeof c.defaults === 'object' && !Array.isArray(c.defaults)
+        ? c.defaults
+        : undefined;
+    return {
+        nodeId: node.id,
+        title: typeof c.title === 'string' ? c.title : undefined,
+        description: typeof c.description === 'string' ? c.description : undefined,
+        fields: toScreenFields(c.fields, variables),
+        kind: objectName ? 'object-form' : 'fields',
+        objectName,
+        mode,
+        defaults,
+        idVariable: typeof c.idVariable === 'string' ? c.idVariable : undefined,
+    };
+}

package/dist/views/metadata-admin/previews/simulator/flow-sim-types.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Shared types for the designer-time flow simulator.
+ *
+ * The simulator is a CLIENT-SIDE, BACKEND-FREE interpreter used to debug a flow
+ * draft inside the visual designer. It NEVER calls a `dataSource`: every
+ * side-effecting node (CRUD / connector / http / script) is MOCKED, so running
+ * a simulation can never write or delete real data and never needs a live
+ * environment. Its guiding rule (per design review) is: *never silently
+ * simulate semantics that differ from the runtime* — anything we cannot
+ * faithfully model (join synchronization, subflows, boundary events, arbitrary
+ * script code) is surfaced as an explicit pause/notice instead of a fake
+ * "success".
+ */
+export interface SimNode {
+    id: string;
+    type: string;
+    label?: string;
+    config?: Record<string, unknown>;
+    connectorConfig?: Record<string, unknown>;
+    [k: string]: unknown;
+}
+export interface SimEdge {
+    id?: string;
+    source: string;
+    target: string;
+    condition?: string | {
+        source?: string;
+    };
+    isDefault?: boolean;
+    label?: string;
+    /**
+     * Connection type (FlowEdgeSchema). A `'back'` edge is an ADR-0044 declared
+     * back-edge: traversed normally at run time, but excluded from DAG cycle
+     * validation so a revise/rework loop can re-enter an earlier node.
+     */
+    type?: string;
+}
+export type SimStatus = 'idle' | 'running' | 'paused' | 'done' | 'error';
+/** One evaluated outgoing edge of a decision (kept for the debug timeline). */
+export interface SimEdgeEval {
+    edgeId: string;
+    target: string;
+    condition?: string;
+    result: boolean;
+    error?: string;
+    isDefault?: boolean;
+    selected: boolean;
+}
+export type SimStepStatus = 'ok' | 'mocked' | 'paused' | 'skipped' | 'error';
+/** A single executed node, rich enough to debug decisions and data writes. */
+export interface SimStep {
+    seq: number;
+    nodeId: string;
+    type: string;
+    label: string;
+    status: SimStepStatus;
+    /** Variable names → values written by this node (mocked side effects). */
+    wrote?: Record<string, unknown>;
+    /** Per-edge condition diagnostics for a decision node. */
+    edges?: SimEdgeEval[];
+    /** Human-readable note (e.g. "mocked", "paused for screen input"). */
+    note?: string;
+    /** Evaluation/structural error surfaced to the author. */
+    error?: string;
+}
+export interface SimState {
+    status: SimStatus;
+    variables: Record<string, unknown>;
+    steps: SimStep[];
+    /** Node ids waiting to execute. */
+    frontier: string[];
+    /** Last executed (or currently paused) node. */
+    activeNodeId: string | null;
+    visitedNodeIds: string[];
+    traversedEdgeIds: string[];
+    /** Set while `status === 'paused'` ("wait" or "screen"). */
+    pausedReason?: string;
+    error?: string;
+}
+export type DiagnosticLevel = 'error' | 'warning';
+export interface Diagnostic {
+    level: DiagnosticLevel;
+    nodeId?: string;
+    message: string;
+    /**
+     * For a cycle error: the node path that closes the loop (e.g. `['a','b','a']`),
+     * so the designer can paint the offending edges/nodes inline on the canvas.
+     */
+    cycle?: string[];
+}
+export interface FlowValidation {
+    errors: Diagnostic[];
+    warnings: Diagnostic[];
+    /** Resolved entry node id, when exactly one is determinable. */
+    startNodeId?: string;
+}
+/**
+ * Author-supplied mock outputs, keyed by node id. The value is merged into the
+ * simulation variables according to the node type (single `outputVariable` or a
+ * `outputVariables` list). For a `screen` node it supplies the captured inputs.
+ */
+export type MockResults = Record<string, unknown>;

package/dist/views/metadata-admin/previews/simulator/flow-sim-types.js

@@ -0,0 +1,2 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+export {};

package/dist/views/metadata-admin/previews/simulator/flow-sim-validate.d.ts

@@ -0,0 +1,15 @@
+import type { FlowValidation, SimEdge, SimNode } from './flow-sim-types';
+/** Evaluate a CEL condition, capturing (not swallowing) any failure. */
+export declare function evalCondition(expr: string, variables: Record<string, unknown>): {
+    result: boolean;
+    error?: string;
+};
+/**
+ * Find a directed cycle in `edges` over `nodeIds`, returned as the node path
+ * that closes the loop (e.g. `['a','b','a']`), or `null` when the graph is a
+ * DAG. Iterative DFS with a recursion-stack colour map; the first cycle found
+ * wins (enough to report — the author fixes one at a time).
+ */
+export declare function findCycle(nodeIds: string[], edges: SimEdge[]): string[] | null;
+/** Static structural checks; `errors` block Run, `warnings` are advisory. */
+export declare function validateFlowDraft(nodes: SimNode[], edges: SimEdge[]): FlowValidation;

package/dist/views/metadata-admin/previews/simulator/flow-sim-validate.js

@@ -0,0 +1,185 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+/**
+ * Preflight graph validation + CEL helpers for the flow simulator.
+ *
+ * Validation runs BEFORE a simulation so the debugger refuses to "Run" a
+ * structurally broken flow (which the real runtime would reject) instead of
+ * producing misleading partial output. Condition evaluation deliberately does
+ * NOT swallow errors the way the shared `evaluatePlainCondition` does — a
+ * debugger must tell the author *why* a branch was false (parse error, missing
+ * variable, type error), so we capture and surface the message.
+ */
+import { ExpressionEvaluator } from '@object-ui/core';
+const edgeCondString = (c) => typeof c === 'string' ? c : undefined;
+/** Evaluate a CEL condition, capturing (not swallowing) any failure. */
+export function evalCondition(expr, variables) {
+    const source = expr.trim();
+    if (!source)
+        return { result: false, error: 'Empty condition.' };
+    try {
+        const evaluator = new ExpressionEvaluator({ ...variables, data: variables });
+        const isTemplate = /\$\{/.test(source);
+        const raw = isTemplate
+            ? evaluator.evaluate(source, { throwOnError: true })
+            : evaluator.evaluateExpression(source);
+        return { result: raw === true };
+    }
+    catch (err) {
+        return { result: false, error: err.message || 'Evaluation failed.' };
+    }
+}
+/**
+ * Find a directed cycle in `edges` over `nodeIds`, returned as the node path
+ * that closes the loop (e.g. `['a','b','a']`), or `null` when the graph is a
+ * DAG. Iterative DFS with a recursion-stack colour map; the first cycle found
+ * wins (enough to report — the author fixes one at a time).
+ */
+export function findCycle(nodeIds, edges) {
+    const adj = new Map();
+    for (const id of nodeIds)
+        adj.set(id, []);
+    for (const e of edges) {
+        if (adj.has(e.source) && adj.has(e.target))
+            adj.get(e.source).push(e.target);
+    }
+    const WHITE = 0, GRAY = 1, BLACK = 2;
+    const color = new Map(nodeIds.map((id) => [id, WHITE]));
+    const stack = [];
+    const visit = (start) => {
+        // Explicit stack of {node, next-child-index} frames so a deep graph can't
+        // blow the JS call stack.
+        const frames = [{ id: start, i: 0 }];
+        color.set(start, GRAY);
+        stack.push(start);
+        while (frames.length) {
+            const frame = frames[frames.length - 1];
+            const children = adj.get(frame.id) ?? [];
+            if (frame.i < children.length) {
+                const next = children[frame.i++];
+                const c = color.get(next);
+                if (c === GRAY) {
+                    // Back into the active path → cycle. Slice from `next` to close it.
+                    const from = stack.indexOf(next);
+                    return [...stack.slice(from), next];
+                }
+                if (c === WHITE) {
+                    color.set(next, GRAY);
+                    stack.push(next);
+                    frames.push({ id: next, i: 0 });
+                }
+            }
+            else {
+                color.set(frame.id, BLACK);
+                stack.pop();
+                frames.pop();
+            }
+        }
+        return null;
+    };
+    for (const id of nodeIds) {
+        if (color.get(id) === WHITE) {
+            const cycle = visit(id);
+            if (cycle)
+                return cycle;
+        }
+    }
+    return null;
+}
+/** Static structural checks; `errors` block Run, `warnings` are advisory. */
+export function validateFlowDraft(nodes, edges) {
+    const errors = [];
+    const warnings = [];
+    const ids = nodes.map((n) => n.id);
+    const idSet = new Set();
+    for (const id of ids) {
+        if (!id) {
+            errors.push({ level: 'error', message: 'A node is missing an id.' });
+            continue;
+        }
+        if (idSet.has(id))
+            errors.push({ level: 'error', nodeId: id, message: `Duplicate node id "${id}".` });
+        idSet.add(id);
+    }
+    for (const e of edges) {
+        if (!idSet.has(e.source))
+            errors.push({ level: 'error', message: `Edge source "${e.source}" does not exist.` });
+        if (!idSet.has(e.target))
+            errors.push({ level: 'error', message: `Edge target "${e.target}" does not exist.` });
+    }
+    // Entry resolution: prefer an explicit `start` node, else a node with no
+    // incoming edge. Zero or many → the author must fix it before running.
+    const incoming = new Set(edges.map((e) => e.target));
+    const startNodes = nodes.filter((n) => n.type === 'start');
+    const roots = nodes.filter((n) => !incoming.has(n.id));
+    let startNodeId;
+    if (startNodes.length === 1) {
+        startNodeId = startNodes[0].id;
+        if (incoming.has(startNodeId)) {
+            warnings.push({ level: 'warning', nodeId: startNodeId, message: 'Start node has an incoming edge.' });
+        }
+    }
+    else if (startNodes.length > 1) {
+        errors.push({ level: 'error', message: `Flow has ${startNodes.length} start nodes; expected one.` });
+    }
+    else if (roots.length === 1) {
+        startNodeId = roots[0].id;
+        warnings.push({ level: 'warning', nodeId: startNodeId, message: 'No "start" node; using the only root node as the entry.' });
+    }
+    else if (roots.length === 0) {
+        errors.push({ level: 'error', message: 'No entry node (every node has an incoming edge — the graph is fully cyclic).' });
+    }
+    else {
+        errors.push({ level: 'error', message: `Cannot determine a single entry node (${roots.length} candidates). Add a "start" node.` });
+    }
+    // Per-decision: at most one default; warn on missing default (possible dead end).
+    for (const n of nodes) {
+        if (n.type !== 'decision')
+            continue;
+        const out = edges.filter((e) => e.source === n.id);
+        const defaults = out.filter((e) => e.isDefault);
+        if (defaults.length > 1) {
+            errors.push({ level: 'error', nodeId: n.id, message: `Decision "${n.id}" has ${defaults.length} default branches.` });
+        }
+        if (out.length === 0) {
+            warnings.push({ level: 'warning', nodeId: n.id, message: `Decision "${n.id}" has no outgoing branches.` });
+        }
+        else if (defaults.length === 0 && out.every((e) => edgeCondString(e.condition))) {
+            warnings.push({ level: 'warning', nodeId: n.id, message: `Decision "${n.id}" has no default branch; it may dead-end when no condition matches.` });
+        }
+    }
+    // Unreachable nodes (advisory) — BFS from the resolved entry.
+    if (startNodeId) {
+        const reachable = new Set([startNodeId]);
+        const queue = [startNodeId];
+        while (queue.length) {
+            const cur = queue.shift();
+            for (const e of edges) {
+                if (e.source === cur && idSet.has(e.target) && !reachable.has(e.target)) {
+                    reachable.add(e.target);
+                    queue.push(e.target);
+                }
+            }
+        }
+        for (const n of nodes) {
+            if (!reachable.has(n.id)) {
+                warnings.push({ level: 'warning', nodeId: n.id, message: `Node "${n.id}" is unreachable from the entry.` });
+            }
+        }
+    }
+    // DAG-modulo-back-edges (ADR-0044): the engine requires the flow graph MINUS
+    // declared back-edges to be acyclic. A declared revise loop (its closing edge
+    // marked `type: 'back'`) is excluded and passes; any *unmarked* cycle is an
+    // error — the author must opt in, edge by edge, exactly as `registerFlow`
+    // enforces server-side.
+    const forwardEdges = edges.filter((e) => e.type !== 'back');
+    const cycle = findCycle(ids.filter((id) => !!id), forwardEdges);
+    if (cycle) {
+        errors.push({
+            level: 'error',
+            nodeId: cycle[0],
+            cycle,
+            message: `Cycle detected (${cycle.join(' → ')}). Mark the connection that closes the loop as a back-edge (Connection type → Back-edge) to declare an intentional revise/rework loop.`,
+        });
+    }
+    return { errors, warnings, startNodeId };
+}

package/dist/views/metadata-admin/previews/simulator/flow-simulator.d.ts

@@ -0,0 +1,73 @@
+/**
+ * FlowSimulator — a deterministic, backend-free interpreter that walks a flow
+ * draft for designer-time debugging. See `flow-sim-types.ts` for the contract.
+ *
+ * Supported faithfully: start, decision (edge-first CEL routing), the CRUD /
+ * get / http / connector / script(notification|code) side-effects (MOCKED), and
+ * end. `wait`, `screen`, and `approval` PAUSE for manual continuation (an approval
+ * resumes down the chosen decision's branch — approve / reject / revise). `loop` resolves its
+ * collection and exposes the iterator but is a labelled single pass (the edge
+ * model has no separate body/exit edge). `parallel_gateway` fans out WITHOUT
+ * join synchronization; the ADR-0031 structured containers (`parallel`,
+ * `try_catch` — nested body regions), `join_gateway`, `subflow` and
+ * `boundary_event` are marked unsupported rather than faked. A hard step
+ * ceiling guards cycles.
+ */
+import type { MockResults, SimEdge, SimNode, SimState, SimStep } from './flow-sim-types';
+export declare class FlowSimulator {
+    private nodes;
+    private edges;
+    private mocks;
+    private seq;
+    state: SimState;
+    constructor(nodes: SimNode[], edges: SimEdge[]);
+    /** Validate + seed variables and queue the entry node. Returns the validation. */
+    reset(seedVariables?: Record<string, unknown>, mocks?: MockResults): import("./flow-sim-types").FlowValidation;
+    get done(): boolean;
+    /** Execute one queued node. Returns the recorded step, or null when idle. */
+    step(): SimStep | null;
+    /** Run to completion (or until a pause / error). */
+    runToEnd(): SimState;
+    /**
+     * Continue a flow paused on a `wait`, `screen`, or `approval` node.
+     *  - `screenOutputs` — inputs captured from a paused screen.
+     *  - `decision` — the branch an approval resumes down (ADR-0019/0044:
+     *    `approve` / `reject` / `revise`). The run takes ONLY the out-edge whose
+     *    label matches, mirroring how the engine resumes a suspended approval by
+     *    branch label — instead of fanning out to every out-edge.
+     */
+    resume(opts?: {
+        screenOutputs?: Record<string, unknown>;
+        decision?: string;
+    }): void;
+    /**
+     * Resume a suspended approval down the chosen decision's out-edge: the one
+     * whose `label` equals `decision` (case-insensitive — `approve` / `reject` /
+     * `revise`). With no match (or no decision) it falls back to fanning out —
+     * mirroring the engine's unmatched-`branchLabel` fallback — and logs that so
+     * the author notices the unrouted decision.
+     */
+    private resumeApproval;
+    private execute;
+    private executeDecision;
+    /**
+     * assignment node — set flow variables. Normalizes the three authoring
+     * shapes the engine accepts (Studio's `{ assignments: { var: value } }`
+     * map, the example `{ assignments: [{ variable, value }] }` array, and the
+     * legacy flat `{ var: value }`) and interpolates `{var}` templates — so the
+     * Debug run mirrors runtime instead of silently no-oping.
+     */
+    private executeAssignment;
+    /** Resolve `{var}` templates in an assignment value against live variables. */
+    private interpolateValue;
+    private executeLoop;
+    /** Resolve a `{var}` template ref or a plain variable name from `variables`. */
+    private resolveRef;
+    /** Apply a node's mock output to the simulation variables; returns what it wrote. */
+    private applyMock;
+    private mockNote;
+    /** Enqueue every outgoing target (linear nodes have one; parallel fans out). */
+    private enqueueSuccessors;
+    private traverse;
+    private record;
+}