@xdelivered/emberflow 0.2.0

package/dist/src/engine/httpError.d.ts

@@ -0,0 +1,7 @@
+/** A typed error a node can throw to control the HTTP status/body of its operation. */
+export declare class HttpError extends Error {
+    readonly status: number;
+    readonly body?: unknown;
+    constructor(status: number, body?: unknown);
+}
+export declare function isHttpError(e: unknown): e is HttpError;

package/dist/src/engine/httpError.js

@@ -0,0 +1,14 @@
+/** A typed error a node can throw to control the HTTP status/body of its operation. */
+export class HttpError extends Error {
+    status;
+    body;
+    constructor(status, body) {
+        super(`HTTP ${status}`);
+        this.name = 'HttpError';
+        this.status = status;
+        this.body = body;
+    }
+}
+export function isHttpError(e) {
+    return e instanceof HttpError;
+}

package/dist/src/engine/index.d.ts

@@ -0,0 +1,11 @@
+export * from './types.js';
+export * from './registry.js';
+export * from './validation.js';
+export * from './trace.js';
+export * from './executor.js';
+export * from './output.js';
+export * from './publish.js';
+export * from './scenarios.js';
+export * from './httpError.js';
+export * from './schemaCheck.js';
+export * from './authVerify.js';

package/dist/src/engine/index.js

@@ -0,0 +1,11 @@
+export * from './types.js';
+export * from './registry.js';
+export * from './validation.js';
+export * from './trace.js';
+export * from './executor.js';
+export * from './output.js';
+export * from './publish.js';
+export * from './scenarios.js';
+export * from './httpError.js';
+export * from './schemaCheck.js';
+export * from './authVerify.js';

package/dist/src/engine/output.d.ts

@@ -0,0 +1,11 @@
+import type { WorkflowDefinition, WorkflowRun } from './types.js';
+/**
+ * The output a finished run surfaces: the data collected by its Result nodes —
+ * exactly what the Dock's Output tab shows. A run with a single Result that
+ * produced output yields that output directly; multiple Results are keyed by
+ * node label; a run whose Result nodes were all skipped (or has none) yields
+ * undefined. Used to derive a Subflow node's return value on both hosts
+ * (browser store and server run registry), so subflow output follows the same
+ * convention users already see for a run.
+ */
+export declare function runOutput(run: WorkflowRun, flow: WorkflowDefinition): unknown;

package/dist/src/engine/output.js

@@ -0,0 +1,20 @@
+/**
+ * The output a finished run surfaces: the data collected by its Result nodes —
+ * exactly what the Dock's Output tab shows. A run with a single Result that
+ * produced output yields that output directly; multiple Results are keyed by
+ * node label; a run whose Result nodes were all skipped (or has none) yields
+ * undefined. Used to derive a Subflow node's return value on both hosts
+ * (browser store and server run registry), so subflow output follows the same
+ * convention users already see for a run.
+ */
+export function runOutput(run, flow) {
+    const produced = flow.nodes.filter((n) => n.type === 'Result' && run.nodeStates[n.id]?.output !== undefined);
+    if (produced.length === 0)
+        return undefined;
+    if (produced.length === 1)
+        return run.nodeStates[produced[0].id].output;
+    const out = {};
+    for (const n of produced)
+        out[n.label] = run.nodeStates[n.id].output;
+    return out;
+}

package/dist/src/engine/publish.d.ts

@@ -0,0 +1,30 @@
+import type { FieldDefinition, NodeImplementation, WorkflowDefinition } from './types.js';
+import type { NodeRegistry } from './registry.js';
+/**
+ * A sealed, executable flow artifact. Carries the flow, the input schema lifted
+ * from its Input node, and a SHA-256 hash of every node type's implementation
+ * so the runner can refuse to execute a flow whose code has drifted.
+ */
+export interface PublishedArtifact {
+    $artifact: 'emberflow/v1';
+    publishedAt: string;
+    inputSchema: FieldDefinition[];
+    /** node TYPE -> sha256 hex of implementation.toString() */
+    nodeHashes: Record<string, string>;
+    flow: WorkflowDefinition;
+}
+/** SHA-256 hex of an implementation's source text (WebCrypto — browser + Node). */
+export declare function hashImplementation(impl: NodeImplementation): Promise<string>;
+/**
+ * Seal a flow into a PublishedArtifact: validate (error-severity issues throw),
+ * strip pins, lift the input schema, and hash each node type's implementation.
+ */
+export declare function publishFlow(flow: WorkflowDefinition, registry: NodeRegistry, now?: () => string): Promise<PublishedArtifact>;
+/**
+ * Verify every node hash in an artifact against a live registry. Returns the
+ * list of drifted (hash mismatch) or unknown (unregistered) node types; an
+ * empty list means the artifact is safe to execute on this registry.
+ */
+export declare function verifyArtifact(artifact: PublishedArtifact, registry: NodeRegistry): Promise<string[]>;
+/** Structural type guard for a PublishedArtifact envelope. */
+export declare function isArtifact(value: unknown): value is PublishedArtifact;

package/dist/src/engine/publish.js

@@ -0,0 +1,95 @@
+import { validateFlow } from './validation.js';
+const ARTIFACT_TAG = 'emberflow/v1';
+/** SHA-256 hex of an implementation's source text (WebCrypto — browser + Node). */
+export async function hashImplementation(impl) {
+    const bytes = new TextEncoder().encode(impl.toString());
+    const digest = await crypto.subtle.digest('SHA-256', bytes);
+    return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+/** Distinct node types used by a flow, in first-seen order. */
+function distinctTypes(flow) {
+    const seen = [];
+    for (const node of flow.nodes) {
+        if (!seen.includes(node.type))
+            seen.push(node.type);
+    }
+    return seen;
+}
+/** Lift the declared input schema from the flow's first Input node (or []). */
+function liftInputSchema(flow) {
+    const input = flow.nodes.find((n) => n.type === 'Input');
+    const fields = input?.config?.fields;
+    if (!Array.isArray(fields))
+        return [];
+    return fields.filter((f) => f !== null && typeof f === 'object' && typeof f.name === 'string');
+}
+/**
+ * Deep-copy a flow and strip dev-only fixtures: metadata.pinnedOutput from
+ * every node, and top-level scenarios. Both are authoring aids that have no
+ * business shipping in a published artifact.
+ */
+function sealFlow(flow) {
+    const copy = structuredClone(flow);
+    for (const node of copy.nodes) {
+        if (!node.metadata)
+            continue;
+        delete node.metadata.pinnedOutput;
+        if (Object.keys(node.metadata).length === 0)
+            delete node.metadata;
+    }
+    delete copy.scenarios;
+    return copy;
+}
+/**
+ * Seal a flow into a PublishedArtifact: validate (error-severity issues throw),
+ * strip pins, lift the input schema, and hash each node type's implementation.
+ */
+export async function publishFlow(flow, registry, now = () => new Date().toISOString()) {
+    const errors = validateFlow(flow, registry).filter((i) => i.severity === 'error');
+    if (errors.length > 0) {
+        throw new Error(`Cannot publish: ${errors.map((i) => i.message).join('; ')}`);
+    }
+    const sealed = sealFlow(flow);
+    const nodeHashes = {};
+    for (const type of distinctTypes(sealed)) {
+        nodeHashes[type] = await hashImplementation(registry.get(type).implementation);
+    }
+    return {
+        $artifact: ARTIFACT_TAG,
+        publishedAt: now(),
+        inputSchema: liftInputSchema(sealed),
+        nodeHashes,
+        flow: sealed,
+    };
+}
+/**
+ * Verify every node hash in an artifact against a live registry. Returns the
+ * list of drifted (hash mismatch) or unknown (unregistered) node types; an
+ * empty list means the artifact is safe to execute on this registry.
+ */
+export async function verifyArtifact(artifact, registry) {
+    const bad = [];
+    for (const [type, expected] of Object.entries(artifact.nodeHashes)) {
+        if (!registry.has(type)) {
+            bad.push(type);
+            continue;
+        }
+        const actual = await hashImplementation(registry.get(type).implementation);
+        if (actual !== expected)
+            bad.push(type);
+    }
+    return bad;
+}
+/** Structural type guard for a PublishedArtifact envelope. */
+export function isArtifact(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const v = value;
+    return (v.$artifact === ARTIFACT_TAG &&
+        typeof v.publishedAt === 'string' &&
+        Array.isArray(v.inputSchema) &&
+        v.nodeHashes !== null &&
+        typeof v.nodeHashes === 'object' &&
+        v.flow !== null &&
+        typeof v.flow === 'object');
+}

package/dist/src/engine/registry.d.ts

@@ -0,0 +1,34 @@
+import type { NodeDefinition, NodeImplementation } from './types.js';
+export interface RegisteredNode {
+    definition: NodeDefinition;
+    implementation: NodeImplementation;
+}
+export declare class NodeRegistry {
+    nodes: Map<string, RegisteredNode>;
+    sources: Map<string, string>;
+    register(definition: NodeDefinition, implementation: NodeImplementation): void;
+    get(type: string): RegisteredNode;
+    has(type: string): boolean;
+    /**
+     * Replace this registry's contents with another's, in place. Keeps this
+     * object's identity, so references held elsewhere (RunRegistry's execution
+     * registry, request-handler closures) immediately see the new node set. Used
+     * by the project-config hot-reload to pick up agent-authored nodes without a
+     * process restart (which would kill in-flight agent runs).
+     */
+    adopt(other: NodeRegistry): void;
+    list(): NodeDefinition[];
+    /**
+     * Register a definition-only node (metadata fetched from the runner). Its
+     * implementation is a stub that fails loudly if browser-executed — such
+     * nodes run on the server. Never overwrites a real registration.
+     */
+    registerDefinition(definition: NodeDefinition, source?: string): void;
+    /** Source text for display: stored source for definition-only nodes, else the impl's toString(). */
+    getSource(type: string): string | undefined;
+    /**
+     * A fresh registry instance sharing this one's node + source maps — a new
+     * top-level reference (so store subscribers re-render) without copying node data.
+     */
+    withSameNodes(): NodeRegistry;
+}

package/dist/src/engine/registry.js

@@ -0,0 +1,67 @@
+export class NodeRegistry {
+    nodes = new Map();
+    sources = new Map();
+    register(definition, implementation) {
+        if (this.nodes.has(definition.type)) {
+            throw new Error(`Node type already registered: ${definition.type}`);
+        }
+        this.nodes.set(definition.type, { definition, implementation });
+    }
+    get(type) {
+        const node = this.nodes.get(type);
+        if (!node)
+            throw new Error(`Unknown node type: ${type}`);
+        return node;
+    }
+    has(type) {
+        return this.nodes.has(type);
+    }
+    /**
+     * Replace this registry's contents with another's, in place. Keeps this
+     * object's identity, so references held elsewhere (RunRegistry's execution
+     * registry, request-handler closures) immediately see the new node set. Used
+     * by the project-config hot-reload to pick up agent-authored nodes without a
+     * process restart (which would kill in-flight agent runs).
+     */
+    adopt(other) {
+        this.nodes = other.nodes;
+        this.sources = other.sources;
+    }
+    list() {
+        return [...this.nodes.values()].map((n) => n.definition);
+    }
+    /**
+     * Register a definition-only node (metadata fetched from the runner). Its
+     * implementation is a stub that fails loudly if browser-executed — such
+     * nodes run on the server. Never overwrites a real registration.
+     */
+    registerDefinition(definition, source) {
+        if (this.nodes.has(definition.type))
+            return;
+        this.nodes.set(definition.type, {
+            definition,
+            implementation: async () => {
+                throw new Error(`${definition.type} runs on the server — start the runner or switch execution to Server mode`);
+            },
+        });
+        if (source !== undefined)
+            this.sources.set(definition.type, source);
+    }
+    /** Source text for display: stored source for definition-only nodes, else the impl's toString(). */
+    getSource(type) {
+        if (this.sources.has(type))
+            return this.sources.get(type);
+        const node = this.nodes.get(type);
+        return node ? node.implementation.toString() : undefined;
+    }
+    /**
+     * A fresh registry instance sharing this one's node + source maps — a new
+     * top-level reference (so store subscribers re-render) without copying node data.
+     */
+    withSameNodes() {
+        const next = new NodeRegistry();
+        next.nodes = this.nodes;
+        next.sources = this.sources;
+        return next;
+    }
+}

package/dist/src/engine/scenarios.d.ts

@@ -0,0 +1,12 @@
+import type { ScenarioDefinition, WorkflowDefinition } from './types.js';
+/** Find a scenario by name (exact) or id. Returns undefined when absent. */
+export declare function findScenario(flow: WorkflowDefinition, nameOrId: string): ScenarioDefinition | undefined;
+/** Names of a flow's scenarios, for error messages. */
+export declare function scenarioNames(flow: WorkflowDefinition): string[];
+/** Merge an op's flow-level `mocks` with a scenario's `mocks` (scenario wins
+ *  per nodeId) into the map an executor mock run consults. ONE merge shared
+ *  by both places that start a mock run: the live serving path
+ *  (server/index.ts POST /runs, when servingMode === 'mock') and the CLI test
+ *  runner's `--mock` flag (server/testRunner.ts) — so mock semantics can't
+ *  drift between "serve mock" and "test mock". */
+export declare function mergeMocks(flow: WorkflowDefinition, scenario?: ScenarioDefinition): Record<string, unknown>;

package/dist/src/engine/scenarios.js

@@ -0,0 +1,19 @@
+/** Find a scenario by name (exact) or id. Returns undefined when absent. */
+export function findScenario(flow, nameOrId) {
+    return flow.scenarios?.find((s) => s.name === nameOrId || s.id === nameOrId);
+}
+/** Names of a flow's scenarios, for error messages. */
+export function scenarioNames(flow) {
+    return (flow.scenarios ?? []).map((s) => s.name);
+}
+/** Merge an op's flow-level `mocks` with a scenario's `mocks` (scenario wins
+ *  per nodeId) into the map an executor mock run consults. ONE merge shared
+ *  by both places that start a mock run: the live serving path
+ *  (server/index.ts POST /runs, when servingMode === 'mock') and the CLI test
+ *  runner's `--mock` flag (server/testRunner.ts) — so mock semantics can't
+ *  drift between "serve mock" and "test mock". */
+export function mergeMocks(flow, scenario) {
+    const opMocks = (flow.mocks ?? {});
+    const scenarioMocks = (scenario?.mocks ?? {});
+    return { ...opMocks, ...scenarioMocks };
+}

package/dist/src/engine/schemaCheck.d.ts

@@ -0,0 +1,4 @@
+/** Minimal subset validator: object type, required keys, per-property primitive
+ *  type. Returns null when valid, else the first error message. Unknown schema
+ *  shapes impose no constraint (valid) — extend as real schemas demand. */
+export declare function validateAgainstSchema(schema: unknown, value: unknown): string | null;

package/dist/src/engine/schemaCheck.js

@@ -0,0 +1,34 @@
+const typeOfValue = (v) => {
+    if (v === null)
+        return 'null';
+    if (v === undefined)
+        return 'undefined';
+    if (Array.isArray(v))
+        return 'array';
+    return typeof v;
+};
+/** Minimal subset validator: object type, required keys, per-property primitive
+ *  type. Returns null when valid, else the first error message. Unknown schema
+ *  shapes impose no constraint (valid) — extend as real schemas demand. */
+export function validateAgainstSchema(schema, value) {
+    if (!schema || typeof schema !== 'object')
+        return null;
+    const s = schema;
+    if (s.type === 'object') {
+        if (typeOfValue(value) !== 'object')
+            return 'expected an object';
+        const obj = value;
+        for (const key of s.required ?? []) {
+            if (!(key in obj) || obj[key] === undefined)
+                return `missing required field: ${key}`;
+        }
+        for (const [key, spec] of Object.entries(s.properties ?? {})) {
+            if (obj[key] === undefined)
+                continue;
+            if (spec.type && typeOfValue(obj[key]) !== spec.type) {
+                return `field ${key} must be a ${spec.type}`;
+            }
+        }
+    }
+    return null;
+}

package/dist/src/engine/trace.d.ts

@@ -0,0 +1,12 @@
+import type { NodeExecutionSample } from './types.js';
+export interface TraceSink {
+    record(sample: NodeExecutionSample): void;
+    samplesFor(nodeId: string): NodeExecutionSample[];
+    all(): NodeExecutionSample[];
+}
+export declare class InMemoryTraceSink implements TraceSink {
+    private samples;
+    record(sample: NodeExecutionSample): void;
+    samplesFor(nodeId: string): NodeExecutionSample[];
+    all(): NodeExecutionSample[];
+}

package/dist/src/engine/trace.js

@@ -0,0 +1,12 @@
+export class InMemoryTraceSink {
+    samples = [];
+    record(sample) {
+        this.samples.push(sample);
+    }
+    samplesFor(nodeId) {
+        return this.all().filter((s) => s.nodeId === nodeId);
+    }
+    all() {
+        return [...this.samples].reverse();
+    }
+}