@xdelivered/emberflow 0.2.0

package/server/mockServe.test.ts

@@ -0,0 +1,467 @@
+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';
+import { runCli } from './cli';
+
+// Task 6: `--mock` serving. Boots the real runner subprocess twice — once
+// with EMBERFLOW_MOCK=1 (mounted HTTP operations answer from scenario
+// expectations, no nodes execute) and once without (unchanged, real
+// execution) — against a scratch project with two routed operations:
+// `ping` (has scenarios with/without `expect`) and `echo` (no scenarios at
+// all, for the 501 case).
+
+const MOCK_PORT = 8142;
+const LIVE_PORT = 8143;
+const RUNTIME_PORT = 8145;
+const NO_ENV_PORT = 8148;
+const WITH_ENV_PORT = 8149;
+const WITH_ENV_MOCK_PORT = 8150;
+const mockBase = `http://127.0.0.1:${MOCK_PORT}`;
+const liveBase = `http://127.0.0.1:${LIVE_PORT}`;
+const runtimeBase = `http://127.0.0.1:${RUNTIME_PORT}`;
+const noEnvBase = `http://127.0.0.1:${NO_ENV_PORT}`;
+const withEnvBase = `http://127.0.0.1:${WITH_ENV_PORT}`;
+const withEnvMockBase = `http://127.0.0.1:${WITH_ENV_MOCK_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');
+}
+
+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',
+  });
+}
+
+async function postServing(base: string, mode: unknown): Promise<Response> {
+  return fetch(`${base}/serving`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ mode }),
+  });
+}
+
+let mockProc: ChildProcess;
+let liveProc: ChildProcess;
+let runtimeProc: ChildProcess;
+let noEnvProc: ChildProcess;
+let withEnvProc: ChildProcess;
+let withEnvMockProc: ChildProcess;
+let projectDir: string;
+let runtimeProjectDir: string;
+let noEnvProjectDir: string;
+let withEnvProjectDir: string;
+
+/** Writes a minimal routed `ping` op (+ scenario) under `dir`, the smallest
+ * fixture needed to prove which serving mode answered a mounted route. */
+function writePingOp(dir: string): void {
+  mkdirSync(join(dir, 'emberflow', 'apis', 'default'), { recursive: true });
+  writeFileSync(join(dir, 'emberflow.config.mjs'), 'export default {};\n');
+  writeFileSync(
+    join(dir, 'emberflow', 'apis', 'default', 'ping.json'),
+    JSON.stringify({
+      id: 'ping',
+      name: 'Ping',
+      version: 1,
+      createdAt: '2026-01-01T00:00:00Z',
+      updatedAt: '2026-01-01T00:00:00Z',
+      http: { method: 'GET', path: '/ping' },
+      nodes: [
+        {
+          id: 'response',
+          type: 'Response',
+          label: 'Response',
+          position: { x: 0, y: 0 },
+          config: { status: 200, body: { real: true } },
+        },
+      ],
+      edges: [],
+    }),
+  );
+  writeFileSync(
+    join(dir, 'emberflow', 'apis', 'default', 'ping.scenarios.json'),
+    JSON.stringify([{ name: 'ok', input: {}, expect: { status: 200, body: { pong: true } } }]),
+  );
+}
+
+beforeAll(async () => {
+  projectDir = mkdtempSync(join(tmpdir(), 'mockserve-'));
+  mkdirSync(join(projectDir, 'emberflow', 'apis', 'default'), { recursive: true });
+  writeFileSync(join(projectDir, 'emberflow.config.mjs'), 'export default {};\n');
+  // This suite is specifically about the EMBERFLOW_MOCK flag, not the
+  // default-mock-when-unconfigured behavior (covered separately below), so
+  // give the project a configured environment to keep liveBase real.
+  writeFileSync(
+    join(projectDir, 'emberflow.environments.json'),
+    JSON.stringify({
+      defaultEnvironment: 'local',
+      environments: { local: { vars: { BASE_URL: 'http://example.test' }, secrets: {} } },
+    }),
+  );
+
+  // `ping`: a real Response node the mock must NOT execute — its live body
+  // differs from the scenario's mocked body, so a passing assertion proves
+  // which path answered.
+  writeFileSync(
+    join(projectDir, 'emberflow', 'apis', 'default', 'ping.json'),
+    JSON.stringify({
+      id: 'ping',
+      name: 'Ping',
+      version: 1,
+      createdAt: '2026-01-01T00:00:00Z',
+      updatedAt: '2026-01-01T00:00:00Z',
+      http: { method: 'GET', path: '/ping' },
+      nodes: [
+        {
+          id: 'response',
+          type: 'Response',
+          label: 'Response',
+          position: { x: 0, y: 0 },
+          config: { status: 200, body: { real: true } },
+        },
+      ],
+      edges: [],
+    }),
+  );
+  writeFileSync(
+    join(projectDir, 'emberflow', 'apis', 'default', 'ping.scenarios.json'),
+    JSON.stringify([
+      { name: 'ok', input: {}, expect: { status: 200, body: { pong: true } } },
+      { name: 'teapot', input: {}, expect: { status: 418, body: { pong: 'teapot' } } },
+    ]),
+  );
+
+  // `echo`: routed op with a scenario that has NO `expect` — nothing
+  // mockable, so mock mode must answer 501.
+  writeFileSync(
+    join(projectDir, 'emberflow', 'apis', 'default', 'echo.json'),
+    JSON.stringify({
+      id: 'echo',
+      name: 'Echo',
+      version: 1,
+      createdAt: '2026-01-01T00:00:00Z',
+      updatedAt: '2026-01-01T00:00:00Z',
+      http: { method: 'GET', path: '/echo' },
+      nodes: [
+        {
+          id: 'response',
+          type: 'Response',
+          label: 'Response',
+          position: { x: 0, y: 0 },
+          config: { status: 200, body: { real: true } },
+        },
+      ],
+      edges: [],
+    }),
+  );
+  writeFileSync(
+    join(projectDir, 'emberflow', 'apis', 'default', 'echo.scenarios.json'),
+    JSON.stringify([{ name: 'no-expect', input: {} }]),
+  );
+
+  mockProc = bootRunner(MOCK_PORT, { EMBERFLOW_PROJECT: projectDir, EMBERFLOW_MOCK: '1' });
+  liveProc = bootRunner(LIVE_PORT, { EMBERFLOW_PROJECT: projectDir });
+
+  // A second scratch project for the runtime-flip suite below, boot WITHOUT
+  // EMBERFLOW_MOCK (real by default) so POST /serving is what flips it. Also
+  // carries a bearer-protected op so the no-auth-in-mock property stays
+  // test-asserted: real 401s it, mock answers it straight from the scenario.
+  runtimeProjectDir = mkdtempSync(join(tmpdir(), 'mockserve-runtime-'));
+  mkdirSync(join(runtimeProjectDir, 'emberflow', 'apis', 'default'), { recursive: true });
+  mkdirSync(join(runtimeProjectDir, 'emberflow', 'apis', 'secure'), { recursive: true });
+  writeFileSync(join(runtimeProjectDir, 'emberflow.config.mjs'), 'export default {};\n');
+  writeFileSync(
+    join(runtimeProjectDir, 'emberflow.environments.json'),
+    JSON.stringify({
+      defaultEnvironment: 'local',
+      environments: { local: { vars: {}, secrets: { API_TOKEN: 'topsecret' } } },
+    }),
+  );
+  writeFileSync(
+    join(runtimeProjectDir, 'emberflow', 'apis', 'default', 'ping.json'),
+    JSON.stringify({
+      id: 'ping',
+      name: 'Ping',
+      version: 1,
+      createdAt: '2026-01-01T00:00:00Z',
+      updatedAt: '2026-01-01T00:00:00Z',
+      http: { method: 'GET', path: '/ping' },
+      nodes: [
+        {
+          id: 'response',
+          type: 'Response',
+          label: 'Response',
+          position: { x: 0, y: 0 },
+          config: { status: 200, body: { real: true } },
+        },
+      ],
+      edges: [],
+    }),
+  );
+  writeFileSync(
+    join(runtimeProjectDir, 'emberflow', 'apis', 'default', 'ping.scenarios.json'),
+    JSON.stringify([{ name: 'ok', input: {}, expect: { status: 200, body: { pong: true } } }]),
+  );
+  // apis/secure/: every op under here inherits a bearer auth policy — the
+  // real path must enforce it, the mock path must not.
+  writeFileSync(
+    join(runtimeProjectDir, 'emberflow', 'apis', 'secure', '_meta.json'),
+    JSON.stringify({ auth: { scheme: 'bearer', secretRef: 'API_TOKEN' } }),
+  );
+  writeFileSync(
+    join(runtimeProjectDir, 'emberflow', 'apis', 'secure', 'protected.json'),
+    JSON.stringify({
+      id: 'protected',
+      name: 'Protected',
+      version: 1,
+      createdAt: '2026-01-01T00:00:00Z',
+      updatedAt: '2026-01-01T00:00:00Z',
+      http: { method: 'GET', path: '/protected' },
+      nodes: [
+        {
+          id: 'response',
+          type: 'Response',
+          label: 'Response',
+          position: { x: 0, y: 0 },
+          config: { status: 200, body: { real: true } },
+        },
+      ],
+      edges: [],
+    }),
+  );
+  writeFileSync(
+    join(runtimeProjectDir, 'emberflow', 'apis', 'secure', 'protected.scenarios.json'),
+    JSON.stringify([{ name: 'ok', input: {}, expect: { status: 200, body: { mocked: true } } }]),
+  );
+  runtimeProc = bootRunner(RUNTIME_PORT, { EMBERFLOW_PROJECT: runtimeProjectDir });
+
+  // Task 1 (default-mock) fixtures.
+  // No environments file at all, no EMBERFLOW_MOCK: should default to mock.
+  noEnvProjectDir = mkdtempSync(join(tmpdir(), 'mockserve-noenv-'));
+  writePingOp(noEnvProjectDir);
+  noEnvProc = bootRunner(NO_ENV_PORT, { EMBERFLOW_PROJECT: noEnvProjectDir });
+
+  // Environments file WITH a configured environment (non-empty vars),
+  // shared by both the plain-real and the EMBERFLOW_MOCK=1-forces-mock cases.
+  withEnvProjectDir = mkdtempSync(join(tmpdir(), 'mockserve-withenv-'));
+  writePingOp(withEnvProjectDir);
+  writeFileSync(
+    join(withEnvProjectDir, 'emberflow.environments.json'),
+    JSON.stringify({
+      defaultEnvironment: 'local',
+      environments: { local: { vars: { BASE_URL: 'http://example.test' }, secrets: {} } },
+    }),
+  );
+  withEnvProc = bootRunner(WITH_ENV_PORT, { EMBERFLOW_PROJECT: withEnvProjectDir });
+  withEnvMockProc = bootRunner(WITH_ENV_MOCK_PORT, {
+    EMBERFLOW_PROJECT: withEnvProjectDir,
+    EMBERFLOW_MOCK: '1',
+  });
+
+  await Promise.all([
+    waitHealthy(`${mockBase}/healthz`),
+    waitHealthy(`${liveBase}/healthz`),
+    waitHealthy(`${runtimeBase}/healthz`),
+    waitHealthy(`${noEnvBase}/healthz`),
+    waitHealthy(`${withEnvBase}/healthz`),
+    waitHealthy(`${withEnvMockBase}/healthz`),
+  ]);
+}, 20_000);
+
+afterAll(() => {
+  mockProc?.kill();
+  liveProc?.kill();
+  runtimeProc?.kill();
+  noEnvProc?.kill();
+  withEnvProc?.kill();
+  withEnvMockProc?.kill();
+  if (projectDir) rmSync(projectDir, { recursive: true, force: true });
+  if (runtimeProjectDir) rmSync(runtimeProjectDir, { recursive: true, force: true });
+  if (noEnvProjectDir) rmSync(noEnvProjectDir, { recursive: true, force: true });
+  if (withEnvProjectDir) rmSync(withEnvProjectDir, { recursive: true, force: true });
+});
+
+describe('--mock serving', () => {
+  it('healthz reports mock:true under EMBERFLOW_MOCK, mock:false without it', async () => {
+    expect(await (await fetch(`${mockBase}/healthz`)).json()).toMatchObject({ mock: true });
+    expect(await (await fetch(`${liveBase}/healthz`)).json()).toMatchObject({ mock: false });
+  });
+
+  it('answers the default (first-with-expect) scenario, with the mock header', async () => {
+    const res = await fetch(`${mockBase}/ping`);
+    expect(res.status).toBe(200);
+    expect(res.headers.get('x-emberflow-mock')).toBe('true');
+    expect(await res.json()).toEqual({ pong: true });
+  });
+
+  it('selects a named scenario via x-emberflow-scenario', async () => {
+    const res = await fetch(`${mockBase}/ping`, { headers: { 'x-emberflow-scenario': 'teapot' } });
+    expect(res.status).toBe(418);
+    expect(res.headers.get('x-emberflow-mock')).toBe('true');
+    expect(await res.json()).toEqual({ pong: 'teapot' });
+  });
+
+  it('returns 501 for an op whose scenarios lack an expect', async () => {
+    const res = await fetch(`${mockBase}/echo`);
+    expect(res.status).toBe(501);
+    expect(res.headers.get('x-emberflow-mock')).toBe('true');
+  });
+
+  it('without EMBERFLOW_MOCK, the same route executes real nodes (unchanged)', async () => {
+    const res = await fetch(`${liveBase}/ping`);
+    expect(res.status).toBe(200);
+    expect(res.headers.get('x-emberflow-mock')).toBeNull();
+    expect(await res.json()).toEqual({ real: true });
+  });
+});
+
+describe('runtime serving mode (POST /serving)', () => {
+  it('boots real (no EMBERFLOW_MOCK), serves real nodes and enforces auth', async () => {
+    expect(await (await fetch(`${runtimeBase}/healthz`)).json()).toMatchObject({ mock: false });
+
+    const ping = await fetch(`${runtimeBase}/ping`);
+    expect(ping.status).toBe(200);
+    expect(ping.headers.get('x-emberflow-mock')).toBeNull();
+    expect(await ping.json()).toEqual({ real: true });
+
+    // No-auth-in-mock is only meaningful if auth is actually enforced on the
+    // real path first — this op 401s without a token.
+    const unauthed = await fetch(`${runtimeBase}/protected`);
+    expect(unauthed.status).toBe(401);
+  });
+
+  it('POST /serving {mode:"mock"} flips the SAME already-mounted routes to mock, live, no restart', async () => {
+    const flip = await postServing(runtimeBase, 'mock');
+    expect(flip.status).toBe(204);
+
+    expect(await (await fetch(`${runtimeBase}/healthz`)).json()).toMatchObject({ mock: true });
+
+    const ping = await fetch(`${runtimeBase}/ping`);
+    expect(ping.status).toBe(200);
+    expect(ping.headers.get('x-emberflow-mock')).toBe('true');
+    expect(await ping.json()).toEqual({ pong: true });
+
+    // The auth policy wired at mount time is skipped entirely in mock mode:
+    // the same protected route that just 401s in real now answers straight
+    // from the scenario expectation with NO token.
+    const protectedRes = await fetch(`${runtimeBase}/protected`);
+    expect(protectedRes.status).toBe(200);
+    expect(protectedRes.headers.get('x-emberflow-mock')).toBe('true');
+    expect(await protectedRes.json()).toEqual({ mocked: true });
+  });
+
+  it('POST /serving {mode:"real"} flips back — auth and real execution resume on the same routes', async () => {
+    const flip = await postServing(runtimeBase, 'real');
+    expect(flip.status).toBe(204);
+
+    expect(await (await fetch(`${runtimeBase}/healthz`)).json()).toMatchObject({ mock: false });
+
+    const ping = await fetch(`${runtimeBase}/ping`);
+    expect(ping.status).toBe(200);
+    expect(ping.headers.get('x-emberflow-mock')).toBeNull();
+    expect(await ping.json()).toEqual({ real: true });
+
+    const unauthed = await fetch(`${runtimeBase}/protected`);
+    expect(unauthed.status).toBe(401);
+  });
+
+  it('POST /serving with a bogus mode 400s and does not change the live mode', async () => {
+    const res = await postServing(runtimeBase, 'bogus');
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(typeof body.error).toBe('string');
+
+    // Still real from the previous test's flip-back.
+    expect(await (await fetch(`${runtimeBase}/healthz`)).json()).toMatchObject({ mock: false });
+    const ping = await fetch(`${runtimeBase}/ping`);
+    expect(await ping.json()).toEqual({ real: true });
+  });
+});
+
+describe('default serving mode (no environments configured)', () => {
+  it('no environments file, no EMBERFLOW_MOCK: healthz reports mock:true and the mounted route answers mock', async () => {
+    expect(await (await fetch(`${noEnvBase}/healthz`)).json()).toMatchObject({ mock: true });
+
+    const ping = await fetch(`${noEnvBase}/ping`);
+    expect(ping.status).toBe(200);
+    expect(ping.headers.get('x-emberflow-mock')).toBe('true');
+    expect(await ping.json()).toEqual({ pong: true });
+  });
+
+  it('POST /serving {mode:"real"} is still honored with zero envs — permissive override', async () => {
+    const flip = await postServing(noEnvBase, 'real');
+    expect(flip.status).toBe(204);
+
+    expect(await (await fetch(`${noEnvBase}/healthz`)).json()).toMatchObject({ mock: false });
+    const ping = await fetch(`${noEnvBase}/ping`);
+    expect(ping.status).toBe(200);
+    expect(ping.headers.get('x-emberflow-mock')).toBeNull();
+    expect(await ping.json()).toEqual({ real: true });
+
+    // Flip back so this suite's fixture state doesn't leak to later tests.
+    expect((await postServing(noEnvBase, 'mock')).status).toBe(204);
+  });
+
+  it('GET /environments reports configured:false so the studio shows its zero-env onboarding state', async () => {
+    const body = await (await fetch(`${noEnvBase}/environments`)).json();
+    expect(body.configured).toBe(false);
+  });
+
+  it('a project WITH a configured environment (>=1 env) boots real — today\'s behavior, unchanged', async () => {
+    expect(await (await fetch(`${withEnvBase}/healthz`)).json()).toMatchObject({ mock: false });
+    const ping = await fetch(`${withEnvBase}/ping`);
+    expect(ping.status).toBe(200);
+    expect(ping.headers.get('x-emberflow-mock')).toBeNull();
+    expect(await ping.json()).toEqual({ real: true });
+  });
+
+  it('EMBERFLOW_MOCK=1 with environments present still forces mock — unchanged', async () => {
+    expect(await (await fetch(`${withEnvMockBase}/healthz`)).json()).toMatchObject({ mock: true });
+    const ping = await fetch(`${withEnvMockBase}/ping`);
+    expect(ping.status).toBe(200);
+    expect(ping.headers.get('x-emberflow-mock')).toBe('true');
+    expect(await ping.json()).toEqual({ pong: true });
+  });
+});
+
+describe('serving CLI command', () => {
+  const origRunnerUrl = process.env.EMBERFLOW_RUNNER_URL;
+
+  beforeAll(() => {
+    // Drive the CLI (client.ts) against the already-booted runtime runner
+    // above, the same way the register-API bin does.
+    process.env.EMBERFLOW_RUNNER_URL = runtimeBase;
+  });
+
+  afterAll(() => {
+    if (origRunnerUrl === undefined) delete process.env.EMBERFLOW_RUNNER_URL;
+    else process.env.EMBERFLOW_RUNNER_URL = origRunnerUrl;
+  });
+
+  it('serving mock: exit 0, flips the runner to mock (healthz mock:true)', async () => {
+    const code = await runCli(['serving', 'mock']);
+    expect(code).toBe(0);
+    expect(await (await fetch(`${runtimeBase}/healthz`)).json()).toMatchObject({ mock: true });
+
+    // Flip back so this test doesn't leak mock mode to any test that follows.
+    expect(await runCli(['serving', 'real'])).toBe(0);
+    expect(await (await fetch(`${runtimeBase}/healthz`)).json()).toMatchObject({ mock: false });
+  });
+
+  it('serving bogus: exit 2, usage failure, does not change the live mode', async () => {
+    const code = await runCli(['serving', 'bogus']);
+    expect(code).toBe(2);
+    expect(await (await fetch(`${runtimeBase}/healthz`)).json()).toMatchObject({ mock: false });
+  });
+});

package/server/nodesPayload.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest';
+import { NodeRegistry } from '../src/engine';
+import { nodesPayload } from './nodesPayload';
+
+describe('nodesPayload', () => {
+  it('returns each node definition with its implementation source', () => {
+    const r = new NodeRegistry();
+    r.register(
+      { type: 'Shout', label: 'Shout', category: 'demo', tags: ['x'] },
+      async (ctx) => ({ loud: String(ctx.input.text).toUpperCase() }),
+    );
+    const payload = nodesPayload(r);
+    expect(payload.nodes).toHaveLength(1);
+    const node = payload.nodes[0];
+    expect(node.type).toBe('Shout');
+    expect(node.label).toBe('Shout');
+    expect(node.category).toBe('demo');
+    expect(node.tags).toEqual(['x']);
+    expect(node.source).toContain('toUpperCase');
+  });
+
+  it('is JSON-serializable (no functions leak through)', () => {
+    const r = new NodeRegistry();
+    r.register({ type: 'A', label: 'A' }, async () => ({}));
+    const round = JSON.parse(JSON.stringify(nodesPayload(r)));
+    expect(round.nodes[0].type).toBe('A');
+    expect(typeof round.nodes[0].source).toBe('string');
+  });
+});

package/server/nodesPayload.ts

@@ -0,0 +1,26 @@
+import type { NodeDefinition, NodeRegistry } from '../src/engine';
+
+/**
+ * Node metadata served to the studio over HTTP. Definitions carry everything
+ * the UI needs (label, schemas, category, tags); `source` is the
+ * implementation's toString() so the Inspector can show a node's code without
+ * the browser bundling the implementation — the key to consumer nodes
+ * appearing in the palette without a per-project browser build.
+ */
+export interface NodeMetaPayload {
+  nodes: Array<NodeDefinition & { source?: string }>;
+}
+
+export function nodesPayload(registry: NodeRegistry): NodeMetaPayload {
+  return {
+    nodes: registry.list().map((definition) => {
+      let source: string | undefined;
+      try {
+        source = registry.get(definition.type).implementation.toString();
+      } catch {
+        source = undefined;
+      }
+      return { ...definition, source };
+    }),
+  };
+}

package/server/normalizeFlow.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from 'vitest';
+import { seedParamDefaults } from './normalizeFlow';
+import type { WorkflowDefinition, WorkflowNode } from '../src/engine';
+
+function inputNode(config: Record<string, unknown> = {}): WorkflowNode {
+  return { id: 'input', type: 'Input', label: 'Input', position: { x: 0, y: 0 }, config };
+}
+
+function flow(over: Partial<WorkflowDefinition> = {}): WorkflowDefinition {
+  return {
+    id: 'f1',
+    name: 'Flow',
+    version: 1,
+    nodes: [],
+    edges: [],
+    createdAt: '2024-01-01T00:00:00.000Z',
+    updatedAt: '2024-01-01T00:00:00.000Z',
+    ...over,
+  } as WorkflowDefinition;
+}
+
+describe('seedParamDefaults', () => {
+  it('seeds only missing keys as "" and returns which were seeded', () => {
+    const f = flow({
+      http: { method: 'GET', path: '/api/channels/:id/approvals/:approvalId' },
+      nodes: [inputNode({ defaults: { params: { id: 'c1' } } })],
+    });
+    const { flow: result, seeded } = seedParamDefaults(f);
+    expect(seeded).toEqual(['approvalId']);
+    const resultInput = result.nodes.find((n) => n.type === 'Input')!;
+    expect((resultInput.config?.defaults as { params: Record<string, unknown> }).params).toEqual({
+      id: 'c1',
+      approvalId: '',
+    });
+  });
+
+  it('never overwrites an existing value', () => {
+    const f = flow({
+      http: { method: 'GET', path: '/api/channels/:id' },
+      nodes: [inputNode({ defaults: { params: { id: 'real-value' } } })],
+    });
+    const { flow: result, seeded } = seedParamDefaults(f);
+    expect(seeded).toEqual([]);
+    const resultInput = result.nodes.find((n) => n.type === 'Input')!;
+    expect((resultInput.config?.defaults as { params: Record<string, unknown> }).params).toEqual({
+      id: 'real-value',
+    });
+  });
+
+  it('is a no-op without an Input node — returns seeded: [] and the same object', () => {
+    const f = flow({ http: { method: 'GET', path: '/api/channels/:id' }, nodes: [] });
+    const { flow: result, seeded } = seedParamDefaults(f);
+    expect(seeded).toEqual([]);
+    expect(result).toBe(f);
+  });
+
+  it('is a no-op without :params in the path — returns seeded: [] and the same object', () => {
+    const f = flow({ http: { method: 'GET', path: '/api/channels' }, nodes: [inputNode()] });
+    const { flow: result, seeded } = seedParamDefaults(f);
+    expect(seeded).toEqual([]);
+    expect(result).toBe(f);
+  });
+
+  it('is a no-op when every param already has a default — returns seeded: [] and the same object', () => {
+    const f = flow({
+      http: { method: 'GET', path: '/api/channels/:id' },
+      nodes: [inputNode({ defaults: { params: { id: '' } } })],
+    });
+    const { flow: result, seeded } = seedParamDefaults(f);
+    expect(seeded).toEqual([]);
+    expect(result).toBe(f);
+  });
+
+  it('is a no-op when there is no http trigger at all', () => {
+    const f = flow({ nodes: [inputNode()] });
+    const { flow: result, seeded } = seedParamDefaults(f);
+    expect(seeded).toEqual([]);
+    expect(result).toBe(f);
+  });
+});

package/server/normalizeFlow.ts

@@ -0,0 +1,59 @@
+import { parsePathParams } from '../src/lib/pathParams';
+import type { WorkflowDefinition, WorkflowNode } from '../src/engine';
+
+export interface SeedParamDefaultsResult {
+  flow: WorkflowDefinition;
+  /** Path-param names that were newly seeded with `''`, in path order. */
+  seeded: string[];
+}
+
+/**
+ * Pure normalization step run before validation/persist on every write path
+ * (PUT /workflows/:id, POST /operations): seeds an empty-string placeholder
+ * under the first Input node's `config.defaults.params` for every `:param`
+ * in `flow.http.path` that has no default yet, so a plain Run reaches nodes
+ * with `params.<name> === ''` instead of crashing on `undefined` (same
+ * scaffold shape `emberflow create` already produces).
+ *
+ * Mirrors the `missing-param-default` guard semantics (src/engine/diagnostics.ts):
+ * presence, not meaningfulness, is what's checked/seeded. No-ops (returning
+ * the SAME `flow` object, unmodified) when there's no `:param` in the path,
+ * no Input node, or every param already has a default — never overwrites an
+ * existing value, whatever it is (including `''`).
+ */
+export function seedParamDefaults(flow: WorkflowDefinition): SeedParamDefaultsResult {
+  const path = flow.http?.path;
+  const params = path ? parsePathParams(path) : [];
+  if (params.length === 0) return { flow, seeded: [] };
+
+  const inputNode = flow.nodes.find((n) => n.type === 'Input');
+  if (!inputNode) return { flow, seeded: [] };
+
+  const existingDefaults = inputNode.config?.defaults as Record<string, unknown> | undefined;
+  const existingParams =
+    existingDefaults && typeof existingDefaults === 'object' && !Array.isArray(existingDefaults)
+      ? (existingDefaults.params as Record<string, unknown> | undefined)
+      : undefined;
+
+  const seeded = params.filter((name) => !existingParams || existingParams[name] === undefined);
+  if (seeded.length === 0) return { flow, seeded: [] };
+
+  const newParams = { ...(existingParams ?? {}) };
+  for (const name of seeded) newParams[name] = '';
+
+  const newInputNode: WorkflowNode = {
+    ...inputNode,
+    config: {
+      ...(inputNode.config ?? {}),
+      defaults: { ...(existingDefaults ?? {}), params: newParams },
+    },
+  };
+
+  return {
+    flow: {
+      ...flow,
+      nodes: flow.nodes.map((n) => (n === inputNode ? newInputNode : n)),
+    },
+    seeded,
+  };
+}

package/server/openBrowser.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from 'vitest';
+import { openBrowser } from './openBrowser';
+
+describe('openBrowser', () => {
+  it('invokes the platform opener with the url', () => {
+    const calls: Array<[string, string[]]> = [];
+    const fakeSpawn = ((cmd: string, args: string[]) => { calls.push([cmd, args]); return { unref() {} }; }) as never;
+    openBrowser('http://localhost:8092', { platform: 'darwin', spawn: fakeSpawn });
+    expect(calls[0][0]).toBe('open');
+    expect(calls[0][1]).toContain('http://localhost:8092');
+  });
+
+  it('uses xdg-open on linux and start on win32', () => {
+    const seen: string[] = [];
+    const fakeSpawn = ((cmd: string) => { seen.push(cmd); return { unref() {} }; }) as never;
+    openBrowser('http://x', { platform: 'linux', spawn: fakeSpawn });
+    openBrowser('http://x', { platform: 'win32', spawn: fakeSpawn });
+    expect(seen).toEqual(['xdg-open', 'cmd']);
+  });
+});