@xdelivered/emberflow 0.2.0

package/server/environmentsRoute.test.ts

@@ -0,0 +1,385 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { spawn, type ChildProcess } from 'node:child_process';
+import { createServer, type Server } from 'node:http';
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+// Verifies GET /environments reports auth status and POST /environments/:name/login
+// performs the login flow, persisting the captured credential (Task 5).
+// Boots the actual runner subprocess (server/index.ts) against a scratch
+// project dir, mirroring the harness in apiMount.test.ts / runsAuth.test.ts.
+
+let proc: ChildProcess;
+const PORT = 8131;
+const base = `http://127.0.0.1:${PORT}`;
+let projectDir: string;
+
+let loginServer: Server;
+const LOGIN_PORT = 8132;
+let concurrentLoginHits = 0;
+
+// Single-node flow: an Input node that just echoes whatever input the run
+// was invoked with (including `headers`) — reused from runsAuth.test.ts's
+// harness pattern to prove the run-auto-attach-after-PUT-secret case.
+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, environment: 'runattach' }),
+  });
+  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;
+}
+
+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',
+  });
+}
+
+beforeAll(async () => {
+  // Tiny stub login target: responds 200 with a Set-Cookie header.
+  loginServer = createServer((req, res) => {
+    if (req.url === '/login-concurrent') concurrentLoginHits += 1;
+    res.setHeader('Set-Cookie', 'session=captured-token; Path=/');
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ ok: true }));
+  });
+  await new Promise<void>((resolve) => loginServer.listen(LOGIN_PORT, resolve));
+
+  projectDir = mkdtempSync(join(tmpdir(), 'envroute-'));
+  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: 'dev',
+      environments: {
+        dev: {
+          vars: {},
+          secrets: {},
+          auth: {
+            attach: { as: 'cookie', name: 'session', secretRef: 'sessionCookie' },
+            login: {
+              request: { method: 'POST', url: `http://127.0.0.1:${LOGIN_PORT}/login` },
+              capture: { from: 'set-cookie', cookieName: 'session' },
+            },
+          },
+        },
+        noauth: {
+          vars: {},
+          secrets: {},
+        },
+        concurrent: {
+          vars: {},
+          secrets: {},
+          auth: {
+            attach: { as: 'cookie', name: 'session', secretRef: 'sessionCookie' },
+            login: {
+              request: { method: 'POST', url: `http://127.0.0.1:${LOGIN_PORT}/login-concurrent` },
+              capture: { from: 'set-cookie', cookieName: 'session' },
+            },
+          },
+        },
+        secrettest: {
+          vars: {},
+          secrets: {},
+        },
+        authtest: {
+          vars: {},
+          secrets: {},
+        },
+        runattach: {
+          vars: {},
+          secrets: {},
+          auth: { attach: { as: 'cookie', name: 'session', secretRef: 'sessionCookie' } },
+        },
+      },
+    }),
+  );
+
+  proc = bootRunner(PORT, { EMBERFLOW_PROJECT: projectDir });
+  await waitHealthy(`${base}/healthz`);
+}, 20_000);
+
+afterAll(async () => {
+  proc?.kill();
+  await new Promise<void>((resolve) => loginServer.close(() => resolve()));
+  if (projectDir) rmSync(projectDir, { recursive: true, force: true });
+});
+
+describe('GET /environments auth status', () => {
+  it('reports configured true, authenticated false when no secret is stored yet', async () => {
+    const res = await fetch(`${base}/api/environments`);
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    const dev = body.environments.find((e: { name: string }) => e.name === 'dev');
+    expect(dev.auth).toEqual({
+      configured: true,
+      authenticated: false,
+      secretRef: 'sessionCookie',
+      config: {
+        attach: { as: 'cookie', name: 'session', secretRef: 'sessionCookie' },
+        login: {
+          request: { method: 'POST', url: `http://127.0.0.1:${LOGIN_PORT}/login` },
+          capture: { from: 'set-cookie', cookieName: 'session' },
+        },
+      },
+    });
+  });
+
+  it('omits auth.configured=false env cleanly (no auth block details leak)', async () => {
+    const res = await fetch(`${base}/api/environments`);
+    const body = await res.json();
+    const noauth = body.environments.find((e: { name: string }) => e.name === 'noauth');
+    expect(noauth.auth).toEqual({ configured: false, authenticated: false });
+  });
+
+  it('reports configured:true for a project with an environments file', async () => {
+    const res = await fetch(`${base}/api/environments`);
+    const body = await res.json();
+    expect(body.configured).toBe(true);
+  });
+
+  it('re-reads the environments file on each GET — agent edits appear without a restart', async () => {
+    const envPath = join(projectDir, 'emberflow.environments.json');
+    const file = JSON.parse(readFileSync(envPath, 'utf8'));
+    file.environments.staging = { vars: { BASE_URL: 'https://staging.example.com' } };
+    writeFileSync(envPath, JSON.stringify(file, null, 2));
+
+    const res = await fetch(`${base}/api/environments`);
+    const body = await res.json();
+    const staging = body.environments.find((e: { name: string }) => e.name === 'staging');
+    expect(staging).toBeDefined();
+    expect(staging.varKeys).toEqual(['BASE_URL']);
+  });
+});
+
+describe('POST /environments/:name/login', () => {
+  it('400s when the environment has no auth.login configured', async () => {
+    const res = await fetch(`${base}/api/environments/noauth/login`, { method: 'POST' });
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error).toBeTruthy();
+  });
+
+  it('performs the login, returns authenticated:true, and updates GET /environments in-process', async () => {
+    const res = await fetch(`${base}/api/environments/dev/login`, { method: 'POST' });
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body).toEqual({ authenticated: true, secretRef: 'sessionCookie' });
+    // no secret value ever returned
+    expect(JSON.stringify(body)).not.toContain('captured-token');
+
+    const getRes = await fetch(`${base}/api/environments`);
+    const getBody = await getRes.json();
+    const dev = getBody.environments.find((e: { name: string }) => e.name === 'dev');
+    expect(dev.auth).toEqual({
+      configured: true,
+      authenticated: true,
+      secretRef: 'sessionCookie',
+      config: {
+        attach: { as: 'cookie', name: 'session', secretRef: 'sessionCookie' },
+        login: {
+          request: { method: 'POST', url: `http://127.0.0.1:${LOGIN_PORT}/login` },
+          capture: { from: 'set-cookie', cookieName: 'session' },
+        },
+      },
+    });
+  });
+
+  it('single-flights two concurrent POST logins to the same environment: upstream hit exactly once, both responses 200', async () => {
+    expect(concurrentLoginHits).toBe(0);
+    const [res1, res2] = await Promise.all([
+      fetch(`${base}/api/environments/concurrent/login`, { method: 'POST' }),
+      fetch(`${base}/api/environments/concurrent/login`, { method: 'POST' }),
+    ]);
+    expect(res1.status).toBe(200);
+    expect(res2.status).toBe(200);
+    const [body1, body2] = await Promise.all([res1.json(), res2.json()]);
+    expect(body1).toEqual({ authenticated: true, secretRef: 'sessionCookie' });
+    expect(body2).toEqual({ authenticated: true, secretRef: 'sessionCookie' });
+    expect(concurrentLoginHits).toBe(1);
+  });
+});
+
+describe('PUT /environments/:name/secrets/:key', () => {
+  it('404s for an unknown environment', async () => {
+    const res = await fetch(`${base}/api/environments/nope/secrets/foo`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ value: 'x' }),
+    });
+    expect(res.status).toBe(404);
+    const body = await res.json();
+    expect(body.error).toBeTruthy();
+  });
+
+  it('400s when value is missing or not a string', async () => {
+    const missing = await fetch(`${base}/api/environments/secrettest/secrets/apiKey`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({}),
+    });
+    expect(missing.status).toBe(400);
+    expect((await missing.json()).error).toBeTruthy();
+
+    const nonString = await fetch(`${base}/api/environments/secrettest/secrets/apiKey`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ value: 42 }),
+    });
+    expect(nonString.status).toBe(400);
+    expect((await nonString.json()).error).toBeTruthy();
+  });
+
+  it('204s with an empty body, never echoing the value, and GET /environments shows the key (not the value)', async () => {
+    const putRes = await fetch(`${base}/api/environments/secrettest/secrets/apiKey`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ value: 'super-secret-value' }),
+    });
+    expect(putRes.status).toBe(204);
+    const text = await putRes.text();
+    expect(text).toBe('');
+    expect(text).not.toContain('super-secret-value');
+
+    const getRes = await fetch(`${base}/api/environments`);
+    const getBody = await getRes.json();
+    expect(JSON.stringify(getBody)).not.toContain('super-secret-value');
+    const env = getBody.environments.find((e: { name: string }) => e.name === 'secrettest');
+    expect(env.secretKeys).toContain('apiKey');
+  });
+});
+
+describe('DELETE /environments/:name/secrets/:key', () => {
+  it('404s for an unknown environment', async () => {
+    const res = await fetch(`${base}/api/environments/nope/secrets/apiKey`, { method: 'DELETE' });
+    expect(res.status).toBe(404);
+    const body = await res.json();
+    expect(body.error).toBeTruthy();
+  });
+
+  it('204s and removes the key from GET /environments secretKeys', async () => {
+    // Depends on the PUT test above having set secrettest.apiKey.
+    const delRes = await fetch(`${base}/api/environments/secrettest/secrets/apiKey`, { method: 'DELETE' });
+    expect(delRes.status).toBe(204);
+
+    const getRes = await fetch(`${base}/api/environments`);
+    const getBody = await getRes.json();
+    const env = getBody.environments.find((e: { name: string }) => e.name === 'secrettest');
+    expect(env.secretKeys).not.toContain('apiKey');
+  });
+});
+
+describe('PUT /environments/:name/auth', () => {
+  it('404s for an unknown environment', async () => {
+    const res = await fetch(`${base}/api/environments/nope/auth`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ attach: { as: 'cookie', name: 'session', secretRef: 'sessionCookie' } }),
+    });
+    expect(res.status).toBe(404);
+    const body = await res.json();
+    expect(body.error).toBeTruthy();
+  });
+
+  it('400s on an invalid auth shape', async () => {
+    const res = await fetch(`${base}/api/environments/authtest/auth`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ attach: { as: 'nope', name: 'session', secretRef: 'sessionCookie' } }),
+    });
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error).toBeTruthy();
+  });
+
+  it('204s on success and GET /environments reflects auth.config', async () => {
+    const putRes = await fetch(`${base}/api/environments/authtest/auth`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ attach: { as: 'header', name: 'X-Api-Key', secretRef: 'apiKeySecret' } }),
+    });
+    expect(putRes.status).toBe(204);
+    expect(await putRes.text()).toBe('');
+
+    const getRes = await fetch(`${base}/api/environments`);
+    const getBody = await getRes.json();
+    const env = getBody.environments.find((e: { name: string }) => e.name === 'authtest');
+    expect(env.auth.config).toEqual({
+      attach: { as: 'header', name: 'X-Api-Key', secretRef: 'apiKeySecret' },
+    });
+  });
+
+  it('204s clearing auth with a null body, and GET /environments omits config', async () => {
+    const putRes = await fetch(`${base}/api/environments/authtest/auth`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(null),
+    });
+    expect(putRes.status).toBe(204);
+
+    const getRes = await fetch(`${base}/api/environments`);
+    const getBody = await getRes.json();
+    const env = getBody.environments.find((e: { name: string }) => e.name === 'authtest');
+    expect(env.auth).toEqual({ configured: false, authenticated: false });
+  });
+});
+
+describe('a run auto-attaches a PUT-set secret (proves in-memory refresh)', () => {
+  it('attaches the session cookie from a secret set via PUT, without a restart', async () => {
+    const putRes = await fetch(`${base}/api/environments/runattach/secrets/sessionCookie`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ value: 'freshly-put-cookie' }),
+    });
+    expect(putRes.status).toBe(204);
+
+    const output = await runAndGetInputOutput({});
+    expect(output.headers.cookie).toContain('session=«secret:sessionCookie»');
+  });
+});

package/server/errorWorkflow.test.ts

@@ -0,0 +1,205 @@
+import { describe, expect, it } from 'vitest';
+import { createDefaultRegistry } from '../src/nodes';
+import type { WorkflowDefinition } from '../src/engine';
+import { RunRegistry, type RunEvent } from './runRegistry';
+
+const base = { version: 1, createdAt: '2026-01-01T00:00:00Z', updatedAt: '2026-01-01T00:00:00Z' };
+
+/** A registry with a node type that always throws — used to force run failures. */
+function registryWithBoom() {
+  const registry = createDefaultRegistry();
+  registry.register({ type: 'boom', label: 'Boom' }, async () => {
+    throw new Error('kaboom');
+  });
+  return registry;
+}
+
+const failingFlow: WorkflowDefinition = {
+  ...base,
+  id: 'failing-flow',
+  name: 'Failing Flow',
+  nodes: [{ id: 'a', type: 'boom', label: 'Boom', position: { x: 0, y: 0 }, config: {} }],
+  edges: [],
+};
+
+/** Error op: an Input node so the run's input is visible via nodeStates.input.input. */
+const errorOp: WorkflowDefinition = {
+  ...base,
+  id: 'error-op',
+  name: 'Error Op',
+  nodes: [
+    { id: 'input', type: 'Input', label: 'Input', position: { x: 0, y: 0 }, config: { fields: [], defaults: {} } },
+  ],
+  edges: [],
+};
+
+const errorOpThatFails: WorkflowDefinition = {
+  ...base,
+  id: 'error-op-boom',
+  name: 'Error Op Boom',
+  nodes: [{ id: 'a', type: 'boom', label: 'Boom', position: { x: 0, y: 0 }, config: {} }],
+  edges: [],
+};
+
+const runOpts = {
+  secrets: {},
+  vars: {},
+  environment: 'test',
+  safeMode: false,
+};
+
+function flowStore(flows: WorkflowDefinition[]) {
+  const byId = new Map(flows.map((f) => [f.id, f]));
+  return (id: string) => byId.get(id);
+}
+
+describe('error workflow', () => {
+  it('fires the configured error op with failure details when a run fails', async () => {
+    const runs = new RunRegistry(flowStore([failingFlow, errorOp]), registryWithBoom(), 'error-op');
+    const { handle } = runs.create(failingFlow, runOpts);
+    const before = new Set([...(runs as unknown as { runs: Map<string, unknown> }).runs.keys()]);
+    await handle.runToEnd();
+
+    // Poll briefly: the error op run is created synchronously inside onRunFinished.
+    const allRunsMap = (runs as unknown as { runs: Map<string, { handle: { run: { workflowId: string; nodeStates: Record<string, { status: string; input?: unknown }> } } }> }).runs;
+    const newIds = [...allRunsMap.keys()].filter((id) => !before.has(id));
+    expect(newIds.length).toBe(1);
+    const errorRunEntry = allRunsMap.get(newIds[0])!;
+    expect(errorRunEntry.handle.run.workflowId).toBe('error-op');
+    const inputState = errorRunEntry.handle.run.nodeStates.input;
+    expect(inputState.status).toBe('succeeded');
+    const capturedInput = (inputState as unknown as { output: { failedWorkflowId: string; failedRunId: string; error: string } }).output;
+    expect(capturedInput.failedWorkflowId).toBe('failing-flow');
+    expect(capturedInput.failedRunId).toBe(handle.run.id);
+    expect(capturedInput.error).toBe('kaboom');
+  });
+
+  it("tags the error-handler run's finished event with errorHandler.firedBy; the failed run carries none", async () => {
+    const runs = new RunRegistry(flowStore([failingFlow, errorOp]), registryWithBoom(), 'error-op');
+    const { handle, runId: failedRunId } = runs.create(failingFlow, runOpts);
+    const before = new Set([...(runs as unknown as { runs: Map<string, unknown> }).runs.keys()]);
+    await handle.runToEnd();
+
+    const allRunsMap = (runs as unknown as { runs: Map<string, unknown> }).runs;
+    const newIds = [...allRunsMap.keys()].filter((id) => !before.has(id));
+    expect(newIds.length).toBe(1);
+    const errorRunId = newIds[0];
+
+    const errorRunEvents: RunEvent[] = [];
+    runs.subscribe(errorRunId, (e) => errorRunEvents.push(e));
+    const errorFinished = errorRunEvents.find((e) => e.type === 'finished');
+    expect(errorFinished?.errorHandler).toEqual({ firedBy: 'failing-flow' });
+
+    const failedRunEvents: RunEvent[] = [];
+    runs.subscribe(failedRunId, (e) => failedRunEvents.push(e));
+    const failedFinished = failedRunEvents.find((e) => e.type === 'finished');
+    expect(failedFinished?.errorHandler).toBeUndefined();
+  });
+
+  it('reports the halting failure, not an earlier fail-soft optional node', async () => {
+    // 'soft' fails first (declaration order) but is optional — fail-soft, the
+    // run continues. 'fatal' then fails and halts the run. The error op must
+    // receive fatal's id/error, not soft's.
+    const mixedFlow: WorkflowDefinition = {
+      ...base,
+      id: 'mixed-flow',
+      name: 'Mixed Flow',
+      nodes: [
+        { id: 'soft', type: 'boom', label: 'Soft Boom', position: { x: 0, y: 0 }, config: {}, optional: true },
+        { id: 'fatal', type: 'boom2', label: 'Fatal Boom', position: { x: 200, y: 0 }, config: {} },
+      ],
+      edges: [],
+    };
+    const registry = registryWithBoom();
+    registry.register({ type: 'boom2', label: 'Boom2' }, async () => {
+      throw new Error('fatal kaboom');
+    });
+    const runs = new RunRegistry(flowStore([mixedFlow, errorOp]), registry, 'error-op');
+    const { handle } = runs.create(mixedFlow, runOpts);
+    const before = new Set([...(runs as unknown as { runs: Map<string, unknown> }).runs.keys()]);
+    await handle.runToEnd();
+
+    const allRunsMap = (runs as unknown as { runs: Map<string, { handle: { run: { workflowId: string; nodeStates: Record<string, { status: string; output?: unknown }> } } }> }).runs;
+    const newIds = [...allRunsMap.keys()].filter((id) => !before.has(id));
+    expect(newIds.length).toBe(1);
+    const inputState = allRunsMap.get(newIds[0])!.handle.run.nodeStates.input;
+    const capturedInput = (inputState as unknown as { output: { failedNodeId: string; error: string } }).output;
+    expect(capturedInput.failedNodeId).toBe('fatal');
+    expect(capturedInput.error).toBe('fatal kaboom');
+  });
+
+  it('does not spawn a third run when the error op itself fails', async () => {
+    const runs = new RunRegistry(flowStore([failingFlow, errorOpThatFails]), registryWithBoom(), 'error-op-boom');
+    const { handle } = runs.create(failingFlow, runOpts);
+    const before = new Set([...(runs as unknown as { runs: Map<string, unknown> }).runs.keys()]);
+    await handle.runToEnd();
+
+    const allRunsMap = (runs as unknown as { runs: Map<string, unknown> }).runs;
+    const newIds = [...allRunsMap.keys()].filter((id) => !before.has(id));
+    // Only the error-op run itself; it must not recurse into a third run.
+    expect(newIds.length).toBe(1);
+  });
+
+  it('does nothing when no errorOperation is configured', async () => {
+    const runs = new RunRegistry(flowStore([failingFlow]), registryWithBoom());
+    const { handle } = runs.create(failingFlow, runOpts);
+    const before = new Set([...(runs as unknown as { runs: Map<string, unknown> }).runs.keys()]);
+    await handle.runToEnd();
+
+    const allRunsMap = (runs as unknown as { runs: Map<string, unknown> }).runs;
+    const newIds = [...allRunsMap.keys()].filter((id) => !before.has(id));
+    expect(newIds.length).toBe(0);
+  });
+
+  it('a failed MOCK run fires its error op as a MOCK run — infra in the error op fails loud instead of executing real', async () => {
+    // The error op carries a db-flavoured node with NO mock: if mock mode did
+    // not propagate, its implementation would run (here: throw a sentinel we
+    // can detect); with propagation it must fail with the infra boundary.
+    const registry = registryWithBoom();
+    let realCalls = 0;
+    registry.register({ type: 'dbWrite', label: 'DB Write', traceKind: 'db' }, async () => {
+      realCalls += 1;
+      return { wrote: true };
+    });
+    const errorOpWithInfra: WorkflowDefinition = {
+      ...base,
+      id: 'error-op-infra',
+      name: 'Error Op Infra',
+      nodes: [{ id: 'log', type: 'dbWrite', label: 'DB Write', position: { x: 0, y: 0 }, config: {} }],
+      edges: [],
+    };
+    const runs = new RunRegistry(flowStore([failingFlow, errorOpWithInfra]), registry, 'error-op-infra');
+    const before = new Set([...(runs as unknown as { runs: Map<string, unknown> }).runs.keys()]);
+    const { handle } = runs.create(failingFlow, { ...runOpts, mockRun: true, mocks: {} });
+    await handle.runToEnd();
+
+    const allRunsMap = (runs as unknown as { runs: Map<string, { handle: { run: { workflowId: string; status: string; nodeStates: Record<string, { status: string; error?: string }> }; runToEnd(): Promise<unknown> } }> }).runs;
+    const newIds = [...allRunsMap.keys()].filter((id) => !before.has(id) && id !== handle.run.id);
+    expect(newIds.length).toBe(1);
+    const errorRun = allRunsMap.get(newIds[0])!.handle;
+    await errorRun.runToEnd().catch(() => {});
+    expect(realCalls).toBe(0);
+    expect(errorRun.run.nodeStates.log.status).toBe('failed');
+    expect(errorRun.run.nodeStates.log.error).toContain('would touch real infrastructure');
+  });
+
+  it('does nothing when the run succeeds', async () => {
+    const okFlow: WorkflowDefinition = {
+      ...base,
+      id: 'ok-flow',
+      name: 'Ok Flow',
+      nodes: [
+        { id: 'input', type: 'Input', label: 'Input', position: { x: 0, y: 0 }, config: { fields: [], defaults: {} } },
+      ],
+      edges: [],
+    };
+    const runs = new RunRegistry(flowStore([okFlow, errorOp]), createDefaultRegistry(), 'error-op');
+    const { handle } = runs.create(okFlow, runOpts);
+    const before = new Set([...(runs as unknown as { runs: Map<string, unknown> }).runs.keys()]);
+    await handle.runToEnd();
+
+    const allRunsMap = (runs as unknown as { runs: Map<string, unknown> }).runs;
+    const newIds = [...allRunsMap.keys()].filter((id) => !before.has(id));
+    expect(newIds.length).toBe(0);
+  });
+});

package/server/flowStore.test.ts

@@ -0,0 +1,84 @@
+import { mkdtempSync, readFileSync, existsSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { FlowStore } from './flowStore';
+import type { WorkflowDefinition } from '../src/engine';
+
+const dirs: string[] = [];
+function scratch(): string {
+  const d = mkdtempSync(join(tmpdir(), 'ef-store-'));
+  dirs.push(d);
+  return d;
+}
+afterEach(() => { for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true }); });
+
+const flow = (id: string, scenarios?: WorkflowDefinition['scenarios']): WorkflowDefinition => ({
+  id, name: id, version: 1, nodes: [], edges: [],
+  createdAt: '2026-01-01T00:00:00Z', updatedAt: '2026-01-01T00:00:00Z',
+  ...(scenarios ? { scenarios } : {}),
+});
+const scenario = { id: 's1', name: 'happy', input: { a: 1 } };
+
+describe('FlowStore scenario sidecars', () => {
+  it('sidecar mode: save splits scenarios into <id>.scenarios.json', () => {
+    const d = scratch();
+    const store = new FlowStore(d, { scenarioSidecars: true });
+    store.save(flow('f1', [scenario]));
+    const onDisk = JSON.parse(readFileSync(join(d, 'f1.json'), 'utf8'));
+    expect(onDisk.scenarios).toBeUndefined();
+    const sidecar = JSON.parse(readFileSync(join(d, 'f1.scenarios.json'), 'utf8'));
+    expect(sidecar).toEqual([scenario]);
+  });
+
+  it('sidecar mode: load and list merge the sidecar back', () => {
+    const d = scratch();
+    const store = new FlowStore(d, { scenarioSidecars: true });
+    store.save(flow('f1', [scenario]));
+    expect(store.load('f1')!.scenarios).toEqual([scenario]);
+    expect(store.list()[0].scenarios).toEqual([scenario]);
+  });
+
+  it('sidecar mode: saving with no scenarios removes a stale sidecar', () => {
+    const d = scratch();
+    const store = new FlowStore(d, { scenarioSidecars: true });
+    store.save(flow('f1', [scenario]));
+    store.save(flow('f1'));
+    expect(existsSync(join(d, 'f1.scenarios.json'))).toBe(false);
+    expect(store.load('f1')!.scenarios).toBeUndefined();
+  });
+
+  it('sidecar mode: hand-authored sidecar is merged even if flow file has none', () => {
+    const d = scratch();
+    writeFileSync(join(d, 'f2.json'), JSON.stringify(flow('f2')));
+    writeFileSync(join(d, 'f2.scenarios.json'), JSON.stringify([scenario]));
+    const store = new FlowStore(d, { scenarioSidecars: true });
+    expect(store.load('f2')!.scenarios).toEqual([scenario]);
+  });
+
+  it('default mode: scenarios stay embedded, no sidecar written', () => {
+    const d = scratch();
+    const store = new FlowStore(d);
+    store.save(flow('f1', [scenario]));
+    const onDisk = JSON.parse(readFileSync(join(d, 'f1.json'), 'utf8'));
+    expect(onDisk.scenarios).toEqual([scenario]);
+    expect(existsSync(join(d, 'f1.scenarios.json'))).toBe(false);
+  });
+
+  it('remove cleans sidecar and seedIfEmpty ignores orphaned sidecars', () => {
+    const d = scratch();
+    const store = new FlowStore(d, { scenarioSidecars: true });
+    store.save(flow('f1', [scenario]));
+    store.remove('f1');
+    expect(existsSync(join(d, 'f1.scenarios.json'))).toBe(false);
+    store.seedIfEmpty([flow('seeded')]);
+    expect(existsSync(join(d, 'seeded.json'))).toBe(true);
+  });
+
+  it('list skips .scenarios.json files as flow candidates in both modes', () => {
+    const d = scratch();
+    const store = new FlowStore(d, { scenarioSidecars: true });
+    store.save(flow('f1', [scenario]));
+    expect(store.list().map((f) => f.id)).toEqual(['f1']);
+  });
+});