@xdelivered/emberflow 0.2.0

package/server/runsAuth.test.ts

@@ -0,0 +1,119 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { spawn, type ChildProcess } from 'node:child_process';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+// Verifies POST /runs auto-attaches the environment's credential (Task 4).
+// Boots the actual runner subprocess (server/index.ts) against a scratch
+// project dir, mirroring the harness in apiMount.test.ts.
+
+let proc: ChildProcess;
+const PORT = 8129;
+const base = `http://127.0.0.1:${PORT}`;
+let projectDir: string;
+
+async function waitHealthy(url: string, tries = 40): Promise<void> {
+  for (let i = 0; i < tries; i++) {
+    try {
+      if ((await fetch(url)).ok) return;
+    } catch {
+      /* not up yet */
+    }
+    await new Promise((r) => setTimeout(r, 150));
+  }
+  throw new Error('runner did not become healthy');
+}
+
+function bootRunner(port: number, env: Record<string, string | undefined>): ChildProcess {
+  return spawn('npx', ['tsx', 'server/index.ts'], {
+    env: { ...process.env, EMBERFLOW_RUNNER_PORT: String(port), ...env },
+    stdio: 'ignore',
+  });
+}
+
+// Single-node flow: an Input node that just echoes whatever input the run
+// was invoked with (including `headers`) — a "trivial flow whose Input
+// echoes headers" per the brief.
+const echoFlow = {
+  id: 'echo-input',
+  name: 'Echo Input',
+  version: 1,
+  createdAt: '2026-01-01T00:00:00Z',
+  updatedAt: '2026-01-01T00:00:00Z',
+  nodes: [
+    {
+      id: 'input',
+      type: 'Input',
+      label: 'Input',
+      position: { x: 0, y: 0 },
+      config: { fields: [], defaults: {} },
+    },
+  ],
+  edges: [],
+};
+
+/** POSTs a step-mode run, steps it once, then reads back the Input node's recorded sample output. */
+async function runAndGetInputOutput(input: Record<string, unknown>): Promise<any> {
+  const createRes = await fetch(`${base}/api/runs`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ flow: echoFlow, mode: 'step', input }),
+  });
+  expect(createRes.status).toBe(201);
+  const { runId } = await createRes.json();
+
+  const stepRes = await fetch(`${base}/api/runs/${runId}/step`, { method: 'POST' });
+  expect(stepRes.status).toBe(200);
+
+  const samplesRes = await fetch(`${base}/api/samples?nodeId=input`);
+  expect(samplesRes.status).toBe(200);
+  const { samples } = await samplesRes.json();
+  const sample = samples.find((s: { runId: string }) => s.runId === runId);
+  expect(sample).toBeDefined();
+  return sample.output;
+}
+
+beforeAll(async () => {
+  projectDir = mkdtempSync(join(tmpdir(), 'runsauth-'));
+  mkdirSync(join(projectDir, 'emberflow', 'apis', 'default'), { recursive: true });
+  writeFileSync(join(projectDir, 'emberflow.config.mjs'), 'export default {};\n');
+  writeFileSync(
+    join(projectDir, 'emberflow.environments.json'),
+    JSON.stringify({
+      defaultEnvironment: 'local',
+      environments: {
+        local: {
+          vars: {},
+          secrets: { sessionCookie: 'supersecretcookievalue' },
+          auth: { attach: { as: 'cookie', name: 'session', secretRef: 'sessionCookie' } },
+        },
+      },
+    }),
+  );
+
+  proc = bootRunner(PORT, { EMBERFLOW_PROJECT: projectDir });
+  await waitHealthy(`${base}/healthz`);
+}, 20_000);
+
+afterAll(() => {
+  proc?.kill();
+  if (projectDir) rmSync(projectDir, { recursive: true, force: true });
+});
+
+describe('POST /runs auto-attaches the environment credential', () => {
+  it('attaches the session cookie from the environment secret when the run omits headers', async () => {
+    // The flow receives the raw secret internally (real attachment happened);
+    // only the studio-facing sample output (via GET /samples) is redacted.
+    // The name= prefix on the redaction token proves attachment occurred.
+    const output = await runAndGetInputOutput({});
+    expect(output.headers.cookie).toContain('session=«secret:sessionCookie»');
+  });
+
+  it('does not overwrite an explicit value for the same cookie name (non-destructive)', async () => {
+    // The run already sets the target cookie name ("session") explicitly —
+    // attachCredential must leave it exactly as the caller set it.
+    const output = await runAndGetInputOutput({ headers: { cookie: 'session=mine' } });
+    expect(output.headers.cookie).toBe('session=mine');
+  });
+});

package/server/runtime/RuntimeAdapter.ts

@@ -0,0 +1,24 @@
+import type { RequestHandler, Router } from 'express';
+
+/** A single routed operation's method + path. */
+export interface RegisteredOp {
+  method: string;
+  path: string;
+}
+
+/**
+ * The seam between the runner and whatever HTTP runtime serves it. Express is
+ * the only implementation today; Deno/Bun adapters can implement this same
+ * interface later without touching the runner.
+ */
+export interface RuntimeAdapter {
+  /** Register a routed operation's handler at `{method, path}`. Throws on a
+   *  duplicate method+path registration. */
+  registerOperation(op: RegisteredOp, handler: RequestHandler): void;
+  /** Mount a sub-router at a base path (used for `/api` + the studio). */
+  mountRouter(basePath: string, router: Router): void;
+  /** Start listening; resolves once the server is up. */
+  listen(port: number, host: string): Promise<void>;
+  /** Stop the server; resolves once fully closed. */
+  close(): Promise<void>;
+}

package/server/runtime/expressAdapter.test.ts

@@ -0,0 +1,38 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { ExpressAdapter } from './expressAdapter';
+
+describe('ExpressAdapter', () => {
+  let adapter: ExpressAdapter | undefined;
+
+  afterEach(async () => {
+    await adapter?.close();
+    adapter = undefined;
+  });
+
+  it('registers an operation route and serves it', async () => {
+    adapter = new ExpressAdapter();
+    adapter.registerOperation({ method: 'GET', path: '/ping' }, (_req, res) => res.json({ pong: true }));
+    await adapter.listen(0, '127.0.0.1');
+    const port = adapter.address?.port;
+    expect(port).toBeTypeOf('number');
+
+    const res = await fetch(`http://127.0.0.1:${port}/ping`);
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ pong: true });
+  });
+
+  it('throws on a duplicate method+path', () => {
+    adapter = new ExpressAdapter();
+    const h = (_req: never, res: { end: () => void }) => res.end();
+    adapter.registerOperation({ method: 'POST', path: '/x' }, h as never);
+    expect(() => adapter?.registerOperation({ method: 'POST', path: '/x' }, h as never)).toThrow(/POST \/x/);
+  });
+
+  it('resolves listen/close cleanly', async () => {
+    adapter = new ExpressAdapter();
+    await adapter.listen(0, '127.0.0.1');
+    expect(adapter.address).not.toBeNull();
+    await adapter.close();
+    expect(adapter.address).toBeNull();
+  });
+});

package/server/runtime/expressAdapter.ts

@@ -0,0 +1,70 @@
+import express, { type Express, type RequestHandler, type Router } from 'express';
+import type { AddressInfo } from 'node:net';
+import type { Server } from 'node:http';
+import type { RegisteredOp, RuntimeAdapter } from './RuntimeAdapter';
+
+const METHODS = ['get', 'post', 'put', 'delete', 'patch'] as const;
+type Method = (typeof METHODS)[number];
+
+function isMethod(m: string): m is Method {
+  return (METHODS as readonly string[]).includes(m);
+}
+
+/** Express implementation of the `RuntimeAdapter` seam. Keep it thin — this is
+ *  the seam other runtimes (Deno/Bun) implement later. */
+export class ExpressAdapter implements RuntimeAdapter {
+  private readonly _app: Express;
+  private server?: Server;
+  private readonly seen = new Set<string>();
+
+  constructor(app?: Express) {
+    this._app = app ?? express();
+  }
+
+  get app(): Express {
+    return this._app;
+  }
+
+  /** The bound address once `listen()` resolves (useful in tests to find an
+   *  ephemeral port). `null` before listening / after close. */
+  get address(): AddressInfo | null {
+    const addr = this.server?.address();
+    return addr && typeof addr === 'object' ? addr : null;
+  }
+
+  registerOperation(op: RegisteredOp, handler: RequestHandler): void {
+    const method = op.method.toUpperCase();
+    const key = `${method} ${op.path}`;
+    if (this.seen.has(key)) {
+      throw new Error(`Duplicate operation route: ${key}`);
+    }
+    const lower = method.toLowerCase();
+    if (!isMethod(lower)) {
+      throw new Error(`Unsupported HTTP method for operation route: ${method} ${op.path}`);
+    }
+    this.seen.add(key);
+    this._app[lower](op.path, handler);
+  }
+
+  mountRouter(basePath: string, router: Router): void {
+    this._app.use(basePath, router);
+  }
+
+  listen(port: number, host: string): Promise<void> {
+    return new Promise((resolve) => {
+      this.server = this._app.listen(port, host, () => resolve());
+    });
+  }
+
+  close(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const server = this.server;
+      if (!server) {
+        resolve();
+        return;
+      }
+      this.server = undefined;
+      server.close((err) => (err ? reject(err) : resolve()));
+    });
+  }
+}

package/server/scenarioTest.test.ts

@@ -0,0 +1,148 @@
+import { describe, expect, it } from 'vitest';
+import { deepSubsetMatch, evaluateExpectation } from './scenarioTest';
+import type { WorkflowDefinition, WorkflowRun } from '../src/engine';
+
+describe('deepSubsetMatch', () => {
+  it('passes on equal primitives', () => {
+    expect(deepSubsetMatch(1, 1)).toEqual([]);
+    expect(deepSubsetMatch('a', 'a')).toEqual([]);
+    expect(deepSubsetMatch(true, true)).toEqual([]);
+  });
+
+  it('fails on unequal primitives', () => {
+    expect(deepSubsetMatch(1, 2)).toEqual(['expected 1, got 2']);
+    expect(deepSubsetMatch('a', 'b')).toEqual(['expected "a", got "b"']);
+  });
+
+  it('passes when actual is a superset of a nested object', () => {
+    const failures = deepSubsetMatch(
+      { user: { name: 'Ada' } },
+      { user: { name: 'Ada', age: 30 }, extra: true },
+    );
+    expect(failures).toEqual([]);
+  });
+
+  it('reports a dotted path for a missing/mismatched nested key', () => {
+    const failures = deepSubsetMatch({ user: { name: 'Ada' } }, { user: { name: 'Bob' } });
+    expect(failures).toEqual(['user.name: expected "Ada", got "Bob"']);
+  });
+
+  it('reports missing actual key', () => {
+    const failures = deepSubsetMatch({ user: { name: 'Ada' } }, { user: {} });
+    expect(failures).toEqual(['user.name: expected "Ada", got undefined']);
+  });
+
+  it('matches arrays index-wise on the expected prefix', () => {
+    expect(deepSubsetMatch([1, 2], [1, 2, 3])).toEqual([]);
+    expect(deepSubsetMatch([1, 2], [1])).toEqual(['[1]: expected 2, got undefined']);
+    expect(deepSubsetMatch([1, 2], [1, 9])).toEqual(['[1]: expected 2, got 9']);
+  });
+
+  it('allows extra actual keys anywhere', () => {
+    expect(deepSubsetMatch({ a: 1 }, { a: 1, b: 2, c: 3 })).toEqual([]);
+  });
+
+  it('null expected matches only null', () => {
+    expect(deepSubsetMatch(null, null)).toEqual([]);
+    expect(deepSubsetMatch(null, undefined)).toEqual(['expected null, got undefined']);
+    expect(deepSubsetMatch(null, 0)).toEqual(['expected null, got 0']);
+  });
+});
+
+function makeFlow(overrides: Partial<WorkflowDefinition> = {}): WorkflowDefinition {
+  return {
+    id: 'flow-1',
+    name: 'Flow 1',
+    version: 1,
+    nodes: [
+      { id: 'response-200', type: 'Response', label: 'OK', position: { x: 0, y: 0 }, config: {} },
+      { id: 'response-401', type: 'Response', label: 'Unauthorized', position: { x: 0, y: 0 }, config: {} },
+    ],
+    edges: [],
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    ...overrides,
+  };
+}
+
+function makeRun(overrides: Partial<WorkflowRun> = {}): WorkflowRun {
+  return {
+    id: 'run-1',
+    workflowId: 'flow-1',
+    status: 'succeeded',
+    startedAt: new Date().toISOString(),
+    nodeStates: {},
+    ...overrides,
+  };
+}
+
+describe('evaluateExpectation', () => {
+  it('passes when status matches', () => {
+    const flow = makeFlow();
+    const run = makeRun({
+      nodeStates: {
+        'response-200': { status: 'succeeded', output: { status: 200, body: { ok: true } } },
+      },
+    });
+    const result = evaluateExpectation(run, flow, { status: 200 });
+    expect(result).toEqual({ ok: true, failures: [] });
+  });
+
+  it('fails when status mismatches', () => {
+    const flow = makeFlow();
+    const run = makeRun({
+      nodeStates: {
+        'response-200': { status: 'succeeded', output: { status: 200, body: {} } },
+      },
+    });
+    const result = evaluateExpectation(run, flow, { status: 401 });
+    expect(result.ok).toBe(false);
+    expect(result.failures).toEqual(['status: expected 401, got 200']);
+  });
+
+  it('fails and lists the dotted path when body is not a subset match', () => {
+    const flow = makeFlow();
+    const run = makeRun({
+      nodeStates: {
+        'response-200': {
+          status: 'succeeded',
+          output: { status: 200, body: { user: { name: 'Bob' } } },
+        },
+      },
+    });
+    const result = evaluateExpectation(run, flow, { body: { user: { name: 'Ada' } } });
+    expect(result.ok).toBe(false);
+    expect(result.failures).toEqual(['body.user.name: expected "Ada", got "Bob"']);
+  });
+
+  it('checks executedNodes against nodeStates, reporting skipped nodes', () => {
+    const flow = makeFlow();
+    const run = makeRun({
+      nodeStates: {
+        'response-200': { status: 'succeeded', output: { status: 200, body: {} } },
+        'response-401': { status: 'skipped' },
+      },
+    });
+    const result = evaluateExpectation(run, flow, { executedNodes: ['response-200', 'response-401'] });
+    expect(result.ok).toBe(false);
+    expect(result.failures).toEqual(['executedNodes: response-401 did not execute (status: skipped)']);
+  });
+
+  it('passes when status, body, and executedNodes all match', () => {
+    const flow = makeFlow();
+    const run = makeRun({
+      nodeStates: {
+        'response-200': {
+          status: 'succeeded',
+          output: { status: 200, body: { user: { name: 'Ada' } } },
+        },
+      },
+    });
+    const result = evaluateExpectation(run, flow, {
+      status: 200,
+      body: { user: { name: 'Ada' } },
+      executedNodes: ['response-200'],
+    });
+    expect(result).toEqual({ ok: true, failures: [] });
+  });
+});

package/server/scenarioTest.ts

@@ -0,0 +1,88 @@
+import type { ScenarioExpectation, WorkflowDefinition, WorkflowRun } from '../src/engine';
+import { extractResponse } from './operationResult';
+
+function fmt(value: unknown): string {
+  if (value === undefined) return 'undefined';
+  return JSON.stringify(value);
+}
+
+/** Deep-subset match: every key/index present in `expected` must match the
+ *  corresponding key/index in `actual`, recursively. Extra keys/indices in
+ *  `actual` are ignored. `null` matches only `null`. Returns human-readable
+ *  failure strings with dotted (and `[i]`) paths; empty array = match. */
+export function deepSubsetMatch(expected: unknown, actual: unknown, path = ''): string[] {
+  const label = path === '' ? '' : `${path}: `;
+
+  if (expected === null) {
+    return actual === null ? [] : [`${label}expected null, got ${fmt(actual)}`];
+  }
+
+  if (Array.isArray(expected)) {
+    if (!Array.isArray(actual)) {
+      return [`${label}expected array, got ${fmt(actual)}`];
+    }
+    const failures: string[] = [];
+    for (let i = 0; i < expected.length; i++) {
+      failures.push(...deepSubsetMatch(expected[i], actual[i], `${path}[${i}]`));
+    }
+    return failures;
+  }
+
+  if (typeof expected === 'object') {
+    if (typeof actual !== 'object' || actual === null || Array.isArray(actual)) {
+      return [`${label}expected object, got ${fmt(actual)}`];
+    }
+    const failures: string[] = [];
+    for (const key of Object.keys(expected as Record<string, unknown>)) {
+      const childPath = path === '' ? key : `${path}.${key}`;
+      failures.push(
+        ...deepSubsetMatch(
+          (expected as Record<string, unknown>)[key],
+          (actual as Record<string, unknown>)[key],
+          childPath,
+        ),
+      );
+    }
+    return failures;
+  }
+
+  // Primitive.
+  return expected === actual ? [] : [`${label}expected ${fmt(expected)}, got ${fmt(actual)}`];
+}
+
+/** Check a scenario's finished run against its `expect` assertion. `status`/
+ *  `body` come from `extractResponse` (the flow's Response-node mapping,
+ *  defaulting to status 200); `executedNodes` checks each id's node state is
+ *  `succeeded`. */
+export function evaluateExpectation(
+  run: WorkflowRun,
+  flow: WorkflowDefinition,
+  expect: ScenarioExpectation,
+): { ok: boolean; failures: string[] } {
+  const failures: string[] = [];
+
+  if (expect.status !== undefined || expect.body !== undefined) {
+    const { status, body } = extractResponse(run, flow);
+
+    if (expect.status !== undefined && expect.status !== status) {
+      failures.push(`status: expected ${expect.status}, got ${status}`);
+    }
+
+    if (expect.body !== undefined) {
+      for (const failure of deepSubsetMatch(expect.body, body)) {
+        failures.push(`body.${failure}`);
+      }
+    }
+  }
+
+  if (expect.executedNodes) {
+    for (const id of expect.executedNodes) {
+      const state = run.nodeStates[id];
+      if (state?.status !== 'succeeded') {
+        failures.push(`executedNodes: ${id} did not execute (status: ${state?.status ?? 'not run'})`);
+      }
+    }
+  }
+
+  return { ok: failures.length === 0, failures };
+}

package/server/setupStatus.test.ts

@@ -0,0 +1,127 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { spawn, type ChildProcess } from 'node:child_process';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+// Boots a real runner subprocess over a temp project (the agentRoute.test.ts
+// pattern) and drives GET /setup-status. Because the route re-reads
+// environments per request, one runner covers both a fresh, unconfigured
+// project AND a project that has just gained an environments file: we assert
+// the fresh shape, then write emberflow.environments.json and re-fetch.
+
+const PORT = 8153;
+const base = `http://127.0.0.1:${PORT}`;
+
+async function waitHealthy(url: string, tries = 40): Promise<void> {
+  for (let i = 0; i < tries; i++) {
+    try {
+      if ((await fetch(url)).ok) return;
+    } catch {
+      /* not up yet */
+    }
+    await new Promise((r) => setTimeout(r, 150));
+  }
+  throw new Error('runner did not become healthy');
+}
+
+let proc: ChildProcess;
+let projectDir: string;
+
+beforeAll(async () => {
+  projectDir = mkdtempSync(join(tmpdir(), 'setupstatus-'));
+  mkdirSync(join(projectDir, 'emberflow', 'apis', 'default'), { recursive: true });
+  writeFileSync(join(projectDir, 'emberflow.config.mjs'), 'export default {};\n');
+  // A pristine project ships exactly the single default/hello example op.
+  writeFileSync(
+    join(projectDir, 'emberflow', 'apis', 'default', 'hello.json'),
+    JSON.stringify({
+      id: 'default/hello',
+      name: 'Hello',
+      version: 1,
+      nodes: [
+        { id: 'in', type: 'Input', label: 'Input', position: { x: 0, y: 0 }, config: {} },
+        { id: 'out', type: 'Result', label: 'Result', position: { x: 300, y: 0 }, config: {}, inputMap: { value: { sourceNodeId: 'in', sourceField: '$' } } },
+      ],
+      edges: [{ id: 'e1', source: 'in', target: 'out' }],
+      createdAt: '2026-07-12T00:00:00Z',
+      updatedAt: '2026-07-12T00:00:00Z',
+    }),
+  );
+
+  proc = spawn('npx', ['tsx', 'server/index.ts'], {
+    env: {
+      ...process.env,
+      EMBERFLOW_RUNNER_PORT: String(PORT),
+      EMBERFLOW_PROJECT: projectDir,
+      // The skills check also looks in the user's home dir (`init --global`);
+      // point homedir() at the temp project so a dev machine with real global
+      // skills doesn't flip the fresh-project assertion.
+      HOME: projectDir,
+      USERPROFILE: projectDir,
+    },
+    stdio: 'ignore',
+  });
+
+  await waitHealthy(`${base}/healthz`);
+}, 20_000);
+
+afterAll(() => {
+  proc?.kill();
+  if (projectDir) rmSync(projectDir, { recursive: true, force: true });
+});
+
+describe('GET /setup-status', () => {
+  it('reports the fresh, unconfigured shape for an init-like project', async () => {
+    const res = await fetch(`${base}/setup-status`);
+    expect(res.status).toBe(200);
+    const body = await res.json();
+
+    expect(Array.isArray(body.agents)).toBe(true);
+    // A fresh project has no environments file → the synthesized fallback is
+    // reported as unconfigured with zero real environments.
+    expect(body.environments).toMatchObject({
+      configured: false,
+      count: 0,
+      protectedCount: 0,
+      anyAuthConfigured: false,
+    });
+    expect(body.skills).toEqual({ claude: false, codex: false });
+    expect(body.ops).toEqual({ count: 1, onlyHello: true });
+    // Inferred from the .mjs config extension (project.language).
+    expect(body.language).toBe('javascript');
+    // Unconfigured projects default to mock serving.
+    expect(body.servingMode).toBe('mock');
+    expect(body.infrastructure).toEqual({ present: false });
+  });
+
+  it('reflects an environments file written after boot (re-read per request)', async () => {
+    writeFileSync(
+      join(projectDir, 'emberflow.environments.json'),
+      JSON.stringify({
+        defaultEnvironment: 'dev',
+        environments: {
+          dev: { vars: {}, secrets: [] },
+          prod: {
+            vars: {},
+            secrets: ['API_KEY'],
+            protected: true,
+            auth: { attach: { as: 'header', name: 'Authorization', secretRef: 'API_KEY' } },
+          },
+        },
+      }),
+    );
+
+    const res = await fetch(`${base}/setup-status`);
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.environments).toEqual({
+      configured: true,
+      count: 2,
+      protectedCount: 1,
+      anyAuthConfigured: true,
+    });
+    // ops are unchanged — still just the hello example.
+    expect(body.ops).toEqual({ count: 1, onlyHello: true });
+  });
+});