@xdelivered/emberflow 0.2.0

package/server/flowStore.ts

@@ -0,0 +1,125 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import type { WorkflowDefinition } from '../src/engine';
+
+export interface FlowStoreOptions {
+  /**
+   * Project mode: scenarios live in <id>.scenarios.json next to the flow
+   * file (reviewable, hand-editable "stories"), not embedded in the flow.
+   */
+  scenarioSidecars?: boolean;
+}
+
+/**
+ * Runner-owned store of workflow files. Each flow lives at `<dir>/<id>.json`,
+ * pretty-printed. The directory is the source of truth when the runner is
+ * online; the browser adopts it on first successful health check.
+ */
+export class FlowStore {
+  readonly dir: string;
+  private readonly sidecars: boolean;
+
+  constructor(dir: string = resolve(process.cwd(), 'workflows'), options: FlowStoreOptions = {}) {
+    this.dir = dir;
+    this.sidecars = options.scenarioSidecars ?? false;
+    mkdirSync(this.dir, { recursive: true });
+  }
+
+  private sidecarPath(id: string): string {
+    return join(this.dir, `${id}.scenarios.json`);
+  }
+
+  /** Merge <id>.scenarios.json into the flow when sidecar mode is on. */
+  private withSidecar(flow: WorkflowDefinition): WorkflowDefinition {
+    if (!this.sidecars) return flow;
+    const path = this.sidecarPath(flow.id);
+    if (!existsSync(path)) return flow;
+    try {
+      const scenarios = JSON.parse(readFileSync(path, 'utf8')) as WorkflowDefinition['scenarios'];
+      return Array.isArray(scenarios) && scenarios.length > 0 ? { ...flow, scenarios } : flow;
+    } catch (err) {
+      console.warn(`[flowStore] skipping unparseable ${flow.id}.scenarios.json: ${String(err)}`);
+      return flow;
+    }
+  }
+
+  /** All parseable *.json flows. Unparseable files are skipped with a warning. */
+  list(): WorkflowDefinition[] {
+    const flows: WorkflowDefinition[] = [];
+    for (const file of readdirSync(this.dir)) {
+      if (!file.endsWith('.json') || file.endsWith('.scenarios.json')) continue;
+      const path = join(this.dir, file);
+      try {
+        const flow = JSON.parse(readFileSync(path, 'utf8')) as WorkflowDefinition;
+        flows.push(this.withSidecar(flow));
+      } catch (err) {
+        console.warn(`[flowStore] skipping unparseable ${file}: ${String(err)}`);
+      }
+    }
+    return flows;
+  }
+
+  /** Load a single flow by id, or undefined when its file is missing/unparseable. */
+  load(id: string): WorkflowDefinition | undefined {
+    const path = join(this.dir, `${id}.json`);
+    if (!existsSync(path)) return undefined;
+    try {
+      const flow = JSON.parse(readFileSync(path, 'utf8')) as WorkflowDefinition;
+      return this.withSidecar(flow);
+    } catch (err) {
+      console.warn(`[flowStore] skipping unparseable ${id}.json: ${String(err)}`);
+      return undefined;
+    }
+  }
+
+  /** Persist a flow. Its id must be a non-empty string and names the file. */
+  save(flow: WorkflowDefinition): void {
+    if (!flow || typeof flow.id !== 'string' || flow.id.length === 0) {
+      throw new Error('Flow must have a non-empty string id');
+    }
+    const path = join(this.dir, `${flow.id}.json`);
+    if (this.sidecars) {
+      const { scenarios, ...rest } = flow;
+      writeFileSync(path, `${JSON.stringify(rest, null, 2)}\n`, 'utf8');
+      const sidecar = this.sidecarPath(flow.id);
+      if (scenarios && scenarios.length > 0) {
+        writeFileSync(sidecar, `${JSON.stringify(scenarios, null, 2)}\n`, 'utf8');
+      } else if (existsSync(sidecar)) {
+        unlinkSync(sidecar);
+      }
+      return;
+    }
+    writeFileSync(path, `${JSON.stringify(flow, null, 2)}\n`, 'utf8');
+  }
+
+  /** Delete a flow file (and any scenario sidecar). Returns false when it did not exist. */
+  remove(id: string): boolean {
+    const sidecar = this.sidecarPath(id);
+    if (existsSync(sidecar)) unlinkSync(sidecar);
+    const path = join(this.dir, `${id}.json`);
+    if (!existsSync(path)) return false;
+    unlinkSync(path);
+    return true;
+  }
+
+  /** Seed the given flows only when the directory holds no json files yet. */
+  seedIfEmpty(flows: WorkflowDefinition[]): void {
+    const hasJson = readdirSync(this.dir).some(
+      (f) => f.endsWith('.json') && !f.endsWith('.scenarios.json'),
+    );
+    if (hasJson) return;
+    for (const flow of flows) this.save(flow);
+  }
+
+  /**
+   * Seed only flows the store doesn't know yet (by id). Existing copies —
+   * possibly user-edited — are never overwritten, so new built-in example
+   * flows appear after an upgrade without clobbering anything.
+   */
+  seedMissing(flows: WorkflowDefinition[]): void {
+    const known = new Set(this.list().map((f) => f.id));
+    for (const flow of flows) {
+      if (!known.has(flow.id)) this.save(flow);
+    }
+  }
+}

package/server/httpOperations.test.ts

@@ -0,0 +1,377 @@
+import express from 'express';
+import type { Server } from 'node:http';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { makeOperationHandler, type OperationRunEnv } from './httpOperations';
+import { extractResponse } from './operationResult';
+import { RunRegistry } from './runRegistry';
+import { createDefaultRegistry } from '../src/nodes';
+import type { AuthPolicy, WorkflowDefinition } from '../src/engine';
+import { createDefaultVerifierRegistry } from './auth/verifiers';
+
+const base = { version: 1, createdAt: '2026-01-01T00:00:00Z', updatedAt: '2026-01-01T00:00:00Z' };
+
+let server: Server | undefined;
+
+/** Boot the op's handler on an ephemeral port; returns the base URL. */
+function boot(op: WorkflowDefinition): Promise<string> {
+  const runs = new RunRegistry(() => undefined, createDefaultRegistry());
+  const app = express();
+  app.use(express.json());
+  const method = op.http!.method.toLowerCase() as 'post' | 'get';
+  app[method](op.http!.path, makeOperationHandler({ runs, op }));
+  return new Promise((resolve) => {
+    server = app.listen(0, '127.0.0.1', () => {
+      const addr = server!.address();
+      const port = typeof addr === 'object' && addr ? addr.port : 0;
+      resolve(`http://127.0.0.1:${port}`);
+    });
+  });
+}
+
+afterEach(async () => {
+  if (!server) return;
+  await new Promise<void>((resolve) => server!.close(() => resolve()));
+  server = undefined;
+});
+
+describe('makeOperationHandler', () => {
+  it('400s when the body fails the input schema', async () => {
+    const op = {
+      ...base,
+      id: 'o',
+      name: 'O',
+      nodes: [],
+      edges: [],
+      http: { method: 'POST', path: '/things', inputSchema: { type: 'object', required: ['name'] } },
+    } as unknown as WorkflowDefinition;
+
+    const url = await boot(op);
+    const res = await fetch(`${url}/things`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({}),
+    });
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error).toMatch(/name/);
+  });
+
+  it('runs the flow and returns the Response node status/body', async () => {
+    // Input node echoes the run's whole input ({params, query, body, headers});
+    // Response node's inputMap pulls `body` from it and pins status to 201.
+    const op = {
+      ...base,
+      id: 'echo',
+      name: 'Echo',
+      http: { method: 'POST', path: '/echo' },
+      nodes: [
+        {
+          id: 'input',
+          type: 'Input',
+          label: 'Input',
+          position: { x: 0, y: 0 },
+          config: { fields: [], defaults: {} },
+        },
+        {
+          id: 'response',
+          type: 'Response',
+          label: 'Response',
+          position: { x: 200, y: 0 },
+          config: { status: 201 },
+          inputMap: {
+            body: { sourceNodeId: 'input', sourceField: 'body' },
+          },
+        },
+      ],
+      edges: [{ id: 'e1', source: 'input', target: 'response' }],
+    } as unknown as WorkflowDefinition;
+
+    const url = await boot(op);
+    const res = await fetch(`${url}/echo`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ id: 42, name: 'widget' }),
+    });
+    expect(res.status).toBe(201);
+    const body = await res.json();
+    expect(body).toEqual({ id: 42, name: 'widget' });
+  });
+});
+
+describe('run input promotes body fields to the top level', () => {
+  it('a flow node reading from(\'input\', \'x\') (a domain field posted in the body) resolves it, while input.body.x still works too', async () => {
+    // Input node echoes the run's whole input; Response node's inputMap
+    // pulls the top-level promoted field (`x`) straight off the Input
+    // node's output as the response body, proving `from('input','x')`
+    // resolves a field that only exists in the posted request body.
+    const op = {
+      ...base,
+      id: 'promote',
+      name: 'Promote',
+      http: { method: 'POST', path: '/promote' },
+      nodes: [
+        {
+          id: 'input',
+          type: 'Input',
+          label: 'Input',
+          position: { x: 0, y: 0 },
+          config: { fields: [], defaults: {} },
+        },
+        {
+          id: 'response',
+          type: 'Response',
+          label: 'Response',
+          position: { x: 200, y: 0 },
+          config: { status: 200 },
+          inputMap: {
+            body: { sourceNodeId: 'input', sourceField: 'x' },
+          },
+        },
+      ],
+      edges: [{ id: 'e1', source: 'input', target: 'response' }],
+    } as unknown as WorkflowDefinition;
+
+    const url = await boot(op);
+    const res = await fetch(`${url}/promote`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ x: 'domain-value' }),
+    });
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body).toBe('domain-value');
+  });
+
+  it('passes the merged input (top-level body fields + body/params/query/headers/user) to runs.create', async () => {
+    const op = {
+      ...base,
+      id: 'spy-op',
+      name: 'SpyOp',
+      nodes: [],
+      edges: [],
+      http: { method: 'POST', path: '/spy' },
+    } as unknown as WorkflowDefinition;
+
+    const createSpy = vi.fn().mockReturnValue({
+      handle: { runToEnd: () => Promise.resolve({ nodeStates: {} } as unknown as import('../src/engine').WorkflowRun) },
+    });
+    const stubRuns = { create: createSpy } as unknown as import('./runRegistry').RunRegistry;
+
+    const app = express();
+    app.use(express.json());
+    app.post(op.http!.path, makeOperationHandler({ runs: stubRuns, op }));
+    server = app.listen(0, '127.0.0.1');
+    await new Promise<void>((resolve) => server!.once('listening', resolve));
+    const addr = server!.address();
+    const port = typeof addr === 'object' && addr ? addr.port : 0;
+
+    await fetch(`http://127.0.0.1:${port}${op.http!.path}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ x: 'domain-value', body: 'shadowed-by-request-body-key' }),
+    });
+
+    expect(createSpy).toHaveBeenCalledTimes(1);
+    const opts = createSpy.mock.calls[0][1] as { input: Record<string, unknown> };
+    // Domain field promoted to the top...
+    expect(opts.input.x).toBe('domain-value');
+    // ...but the request's own `body` key always wins over a same-named
+    // field inside the posted body (params/query/body/headers/user last).
+    expect(opts.input.body).toEqual({ x: 'domain-value', body: 'shadowed-by-request-body-key' });
+  });
+});
+
+describe('auth policy enforcement', () => {
+  const policy: AuthPolicy = { scheme: 'bearer', secretRef: 'T' };
+  const env: OperationRunEnv = { secrets: { T: 'good' }, vars: {}, environment: 'default', safeMode: false };
+
+  // Input node echoes the run's whole input ({params, query, body, headers,
+  // user}); Response node pulls `user` from it so we can assert the resolved
+  // auth `user` was carried into the run input.
+  const op = {
+    ...base,
+    id: 'secure-echo',
+    name: 'SecureEcho',
+    http: { method: 'POST', path: '/secure-echo' },
+    nodes: [
+      {
+        id: 'input',
+        type: 'Input',
+        label: 'Input',
+        position: { x: 0, y: 0 },
+        config: { fields: [], defaults: {} },
+      },
+      {
+        id: 'response',
+        type: 'Response',
+        label: 'Response',
+        position: { x: 200, y: 0 },
+        config: { status: 200 },
+        inputMap: {
+          body: { sourceNodeId: 'input', sourceField: 'user' },
+        },
+      },
+    ],
+    edges: [{ id: 'e1', source: 'input', target: 'response' }],
+  } as unknown as WorkflowDefinition;
+
+  function bootSecure(): Promise<string> {
+    const runs = new RunRegistry(() => undefined, createDefaultRegistry());
+    const verifiers = createDefaultVerifierRegistry();
+    const app = express();
+    app.use(express.json());
+    app.post(op.http!.path, makeOperationHandler({ runs, op, env, policy, verifiers }));
+    return new Promise((resolve) => {
+      server = app.listen(0, '127.0.0.1', () => {
+        const addr = server!.address();
+        const port = typeof addr === 'object' && addr ? addr.port : 0;
+        resolve(`http://127.0.0.1:${port}`);
+      });
+    });
+  }
+
+  it('401s a request with no Authorization header (auth precedes the run/body)', async () => {
+    const url = await bootSecure();
+    const res = await fetch(`${url}${op.http!.path}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({}),
+    });
+    expect(res.status).toBe(401);
+    const body = await res.json();
+    expect(body).toEqual({ error: 'unauthorized' });
+  });
+
+  it('runs and carries `user` into the run input when the bearer token matches', async () => {
+    const url = await bootSecure();
+    const res = await fetch(`${url}${op.http!.path}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Authorization: 'Bearer good' },
+      body: JSON.stringify({}),
+    });
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body).toEqual({ scheme: 'bearer' });
+  });
+});
+
+describe('500 handling', () => {
+  it('returns a generic error body (not the raw message) when a node throws a non-HttpError, and logs the real error server-side', async () => {
+    const secretMessage = 'connection failed: postgres://user:hunter2@db.internal/prod';
+    const op = {
+      ...base,
+      id: 'boom',
+      name: 'Boom',
+      nodes: [],
+      edges: [],
+      http: { method: 'POST', path: '/boom' },
+    } as unknown as WorkflowDefinition;
+
+    // Stub RunRegistry: runToEnd rejects with an Error whose message would
+    // leak a secret if echoed straight to the client.
+    const stubRuns = {
+      create: () => ({
+        runId: 'r1',
+        handle: { runToEnd: () => Promise.reject(new Error(secretMessage)) },
+      }),
+    } as unknown as import('./runRegistry').RunRegistry;
+
+    const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    const app = express();
+    app.use(express.json());
+    app.post(op.http!.path, makeOperationHandler({ runs: stubRuns, op }));
+    server = app.listen(0, '127.0.0.1');
+    await new Promise<void>((resolve) => server!.once('listening', resolve));
+    const addr = server!.address();
+    const port = typeof addr === 'object' && addr ? addr.port : 0;
+
+    const res = await fetch(`http://127.0.0.1:${port}${op.http!.path}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({}),
+    });
+    expect(res.status).toBe(500);
+    const body = await res.json();
+    expect(body).toEqual({ error: 'internal error' });
+    expect(JSON.stringify(body)).not.toMatch(/hunter2/);
+
+    expect(consoleErrorSpy).toHaveBeenCalled();
+    const loggedArgs = consoleErrorSpy.mock.calls.flat();
+    expect(loggedArgs.some((a) => a instanceof Error && a.message === secretMessage)).toBe(true);
+
+    consoleErrorSpy.mockRestore();
+  });
+});
+
+describe('parity: in-studio Run vs live HTTP endpoint', () => {
+  // Same op as the "echo" case above: Input node passes the run's whole
+  // input ({params, query, body, headers}) through; Response node pulls
+  // `body` from it and pins status to 201.
+  const op = {
+    ...base,
+    id: 'echo-parity',
+    name: 'EchoParity',
+    http: { method: 'POST', path: '/echo-parity' },
+    nodes: [
+      {
+        id: 'input',
+        type: 'Input',
+        label: 'Input',
+        position: { x: 0, y: 0 },
+        config: { fields: [], defaults: {} },
+      },
+      {
+        id: 'response',
+        type: 'Response',
+        label: 'Response',
+        position: { x: 200, y: 0 },
+        config: { status: 201 },
+        inputMap: {
+          body: { sourceNodeId: 'input', sourceField: 'body' },
+        },
+      },
+    ],
+    edges: [{ id: 'e1', source: 'input', target: 'response' }],
+  } as unknown as WorkflowDefinition;
+
+  const requestBody = { id: 7, name: 'gizmo' };
+
+  it('the live HTTP endpoint and a direct RunRegistry.create (as the studio Run/scenario would issue) yield identical {status, body}', async () => {
+    // (a) Live HTTP path: makeOperationHandler over an in-process express listen+fetch.
+    const httpRuns = new RunRegistry(() => undefined, createDefaultRegistry());
+    const app = express();
+    app.use(express.json());
+    app.post(op.http!.path, makeOperationHandler({ runs: httpRuns, op }));
+    const url = await new Promise<string>((resolve) => {
+      server = app.listen(0, '127.0.0.1', () => {
+        const addr = server!.address();
+        const port = typeof addr === 'object' && addr ? addr.port : 0;
+        resolve(`http://127.0.0.1:${port}`);
+      });
+    });
+    const httpRes = await fetch(`${url}${op.http!.path}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(requestBody),
+    });
+    const httpResult = { status: httpRes.status, body: await httpRes.json() };
+
+    // (b) In-studio Run path: RunRegistry.create with a scenario-shaped input
+    // ({ body }) — the same request shape an operation scenario carries —
+    // run to completion, then extractResponse maps the Response node output.
+    const studioRuns = new RunRegistry(() => undefined, createDefaultRegistry());
+    const { handle } = studioRuns.create(op, {
+      secrets: {},
+      vars: {},
+      environment: 'default',
+      safeMode: false,
+      input: { body: requestBody },
+    });
+    const run = await handle.runToEnd();
+    const studioResult = extractResponse(run, op);
+
+    expect(studioResult).toEqual(httpResult);
+    expect(httpResult).toEqual({ status: 201, body: requestBody });
+  });
+});

package/server/httpOperations.ts

@@ -0,0 +1,96 @@
+import type { RequestHandler } from 'express';
+import { enforceAuth, isHttpError, validateAgainstSchema, type AuthPolicy, type WorkflowDefinition } from '../src/engine';
+import { extractResponse } from './operationResult';
+import type { RunRegistry } from './runRegistry';
+import type { VerifierRegistry } from './auth/verifiers';
+
+/**
+ * Build the Express handler for a single routed operation: request in
+ * ({params, query, body, headers}), schema-validate the body, run the
+ * operation through the SAME engine path the studio "Run" uses
+ * (`RunRegistry`), map the finished run to an HTTP response.
+ *
+ * The run input is the request body's own fields spread at the top level
+ * (so `from('input', 'ppv')` resolves a domain field posted in the body),
+ * PLUS the full request shape (`params`/`query`/`body`/`headers`/`user`)
+ * layered on top — the latter always wins on key collisions, and ops that
+ * read `input.body.x` keep working unchanged.
+ */
+/** The environment values a routed operation runs with — resolved once at
+ *  boot from the project's default environment (see server/index.ts). Falls
+ *  back to empty secrets/vars when omitted (e.g. in unit tests). */
+export interface OperationRunEnv {
+  secrets: Record<string, string>;
+  vars: Record<string, string>;
+  environment: string;
+  safeMode: boolean;
+}
+
+export function makeOperationHandler(deps: {
+  runs: RunRegistry;
+  op: WorkflowDefinition;
+  env?: OperationRunEnv;
+  policy?: AuthPolicy | null;
+  verifiers?: VerifierRegistry;
+}): RequestHandler {
+  const { runs, op, policy, verifiers } = deps;
+  const env: OperationRunEnv = deps.env ?? { secrets: {}, vars: {}, environment: 'default', safeMode: false };
+  return async (req, res) => {
+    const request = {
+      params: req.params,
+      query: req.query,
+      body: req.body,
+      headers: req.headers,
+    };
+
+    try {
+      // Auth precedes validation: an unauthenticated/misconfigured request
+      // never reaches schema validation or the run, and 401/500 from the
+      // verifier is mapped by the HttpError branch below — never a generic
+      // 500 that could imply the request otherwise would have run.
+      let user: unknown;
+      if (policy) {
+        if (!verifiers) throw new Error('makeOperationHandler: policy set but no verifiers registry provided');
+        ({ user } = enforceAuth({ policy, request, secrets: env.secrets, verifiers }));
+      }
+
+      const schema = op.http?.inputSchema;
+      if (schema) {
+        const error = validateAgainstSchema(schema, request.body);
+        if (error !== null) {
+          res.status(400).json({ error });
+          return;
+        }
+      }
+
+      // Promote the request body's fields to the top of the run input so
+      // flows that read domain fields directly (`from('input', 'ppv')`)
+      // resolve them, while keeping `body` (and params/query/headers/user)
+      // available for ops that read `input.body.x`. Spread the body FIRST
+      // so params/query/body/headers/user always win over a colliding key.
+      const bodyFields =
+        request.body && typeof request.body === 'object' && !Array.isArray(request.body)
+          ? (request.body as Record<string, unknown>)
+          : {};
+      const { handle } = runs.create(op, {
+        ...env,
+        input: { ...bodyFields, ...request, user },
+      });
+      const run = await handle.runToEnd();
+      const { status, body } = extractResponse(run, op);
+      res.status(status).json(body ?? null);
+    } catch (err) {
+      if (isHttpError(err)) {
+        res.status(err.status).json(err.body ?? null);
+        return;
+      }
+      // A node's thrown Error can carry secrets in its message (e.g. a DB
+      // connection string or a URL with an API key) — never echo it to the
+      // (currently unauthenticated) client. Log the real error server-side
+      // and return a generic body instead. HttpError above stays the
+      // sanctioned way for a node to control the client-visible status+body.
+      console.error('[operation] run failed:', err);
+      res.status(500).json({ error: 'internal error' });
+    }
+  };
+}