@xdelivered/emberflow 0.2.0

package/server/client.ts

@@ -0,0 +1,314 @@
+import type {
+  LogLine,
+  NodeExecutionSample,
+  NodeRunState,
+  PublishedArtifact,
+  WorkflowDefinition,
+  WorkflowRun,
+} from '../src/engine';
+import type { ApiTree, FolderNode, ApiNode, OpSummary } from './apiStore';
+
+export type { ApiTree, FolderNode, ApiNode, OpSummary } from './apiStore';
+
+const DEFAULT_BASE_URL = 'http://127.0.0.1:8092';
+
+function baseUrl(): string {
+  return process.env.EMBERFLOW_RUNNER_URL ?? DEFAULT_BASE_URL;
+}
+
+/** SSE-shaped events emitted on GET /runs/:id/events — mirrors server/runRegistry.ts RunEvent. */
+export type RunEvent =
+  | { type: 'nodeState'; nodeId: string; state: NodeRunState }
+  | { type: 'log'; line: LogLine }
+  | { type: 'finished'; run: WorkflowRun };
+
+/** Thrown when the runner cannot be reached at all (connection refused, DNS, etc). */
+export class RunnerUnreachableError extends Error {
+  constructor(cause?: unknown) {
+    super(`runner unreachable at ${baseUrl()} — is \`npm run server\` running?`);
+    this.name = 'RunnerUnreachableError';
+    this.cause = cause;
+  }
+}
+
+async function request<T>(path: string, init?: RequestInit): Promise<T> {
+  let res: Response;
+  try {
+    res = await fetch(`${baseUrl()}${path}`, init);
+  } catch (err) {
+    throw new RunnerUnreachableError(err);
+  }
+  if (!res.ok) {
+    let message = `${res.status} ${res.statusText}`;
+    try {
+      const body = (await res.json()) as { error?: unknown };
+      if (body && typeof body.error === 'string') message = body.error;
+    } catch {
+      /* body wasn't JSON — keep the status text */
+    }
+    throw new Error(message);
+  }
+  if (res.status === 204) return undefined as T;
+  return (await res.json()) as T;
+}
+
+export async function health(): Promise<{ status: string }> {
+  return request('/healthz');
+}
+
+export async function listWorkflows(): Promise<WorkflowDefinition[]> {
+  const { flows } = await request<{ flows: WorkflowDefinition[] }>('/workflows');
+  return flows;
+}
+
+/** Fetches a single flow by id from the full workflow list (no single-flow GET endpoint). */
+export async function getWorkflow(id: string): Promise<WorkflowDefinition | undefined> {
+  const flows = await listWorkflows();
+  return flows.find((f) => f.id === id);
+}
+
+export interface NodeMeta {
+  type: string;
+  label?: string;
+  description?: string;
+  category?: string;
+  traceKind?: string;
+  effects?: string;
+  inputSchema?: unknown;
+  outputSchema?: unknown;
+  source?: string;
+}
+
+/** The runner's LIVE node registry (built-ins + the project's registerNodes),
+ *  so the CLI sees the same nodes execution does — not a project-blind local
+ *  createDefaultRegistry(). */
+export async function listNodes(): Promise<NodeMeta[]> {
+  const { nodes } = await request<{ nodes: NodeMeta[] }>('/nodes');
+  return nodes;
+}
+
+/** Validate a flow against the runner's live registry (built-ins + project nodes). */
+export async function validateOperation(
+  flow: WorkflowDefinition,
+): Promise<{ valid: boolean; issues: unknown[] }> {
+  return request('/validate', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ flow }),
+  });
+}
+
+export async function saveWorkflow(flow: WorkflowDefinition): Promise<void> {
+  await request(`/workflows/${encodeURIComponent(flow.id)}`, {
+    method: 'PUT',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(flow),
+  });
+}
+
+/** One summary per operation with its on-disk `path` (id === path) and `http`
+ *  trigger metadata (undefined for internal sub-flows). Sourced from the
+ *  `operations[]` array of `GET /workflows`. */
+export async function listOperations(): Promise<OpSummary[]> {
+  const { operations } = await request<{ operations: OpSummary[] }>('/workflows');
+  return operations;
+}
+
+/** Builds the API tree (apis → folders → operations) client-side from the flat
+ *  `operations[]` summaries, splitting each op's `path` into [api, …folders, op].
+ *  Mirrors the server's `ApiStore.tree()` so no extra runner route is needed. */
+export async function apiTree(): Promise<ApiTree> {
+  const ops = await listOperations();
+  const apis = new Map<string, ApiNode>();
+  const folderAt = (parent: { folders: FolderNode[] }, name: string): FolderNode => {
+    let f = parent.folders.find((x) => x.name === name);
+    if (!f) { f = { name, folders: [], operations: [] }; parent.folders.push(f); }
+    return f;
+  };
+  for (const op of ops) {
+    const parts = op.path.split('/'); // [api, ...folders, opName]
+    const apiName = parts[0];
+    let api = apis.get(apiName);
+    if (!api) { api = { name: apiName, folders: [], operations: [] }; apis.set(apiName, api); }
+    let container: { folders: FolderNode[]; operations: OpSummary[] } = api;
+    for (const fp of parts.slice(1, -1)) container = folderAt(container, fp);
+    container.operations.push(op);
+  }
+  return { apis: [...apis.values()] };
+}
+
+/** Result of a create-operation attempt: `ok: false` always carries a message
+ *  (e.g. a 409 collision) so a creation failure is never silent. */
+export interface CreateOperationResult { ok: boolean; error?: string }
+
+/**
+ * Creates a brand-new operation at an explicit `apis/` path via
+ * `POST /operations { flow, path }`. The runner enforces `flow.id === path` and
+ * 409s if an operation already exists at that path (never overwrites — that's
+ * `saveWorkflow`/PUT). Mirrors `src/store/serverRunner.ts createOperationOnServer`.
+ */
+/** Delete an operation by id (its apis-tree path). id is URL-encoded so slash
+ *  ids match the /workflows/:id route. Returns ok:false with a message on 404. */
+export async function deleteOperation(id: string): Promise<CreateOperationResult> {
+  let res: Response;
+  try {
+    res = await fetch(`${baseUrl()}/workflows/${encodeURIComponent(id)}`, { method: 'DELETE' });
+  } catch (err) {
+    throw new RunnerUnreachableError(err);
+  }
+  if (res.status === 204 || res.ok) return { ok: true };
+  const body = (await res.json().catch(() => undefined)) as { error?: string } | undefined;
+  return { ok: false, error: body?.error ?? `Delete failed with status ${res.status}` };
+}
+
+export async function createOperation(
+  flow: WorkflowDefinition,
+  path: string,
+): Promise<CreateOperationResult> {
+  let res: Response;
+  try {
+    res = await fetch(`${baseUrl()}/operations`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ flow, path }),
+    });
+  } catch (err) {
+    throw new RunnerUnreachableError(err);
+  }
+  if (res.ok) return { ok: true };
+  const body = (await res.json().catch(() => undefined)) as { error?: string } | undefined;
+  return { ok: false, error: body?.error ?? `Request failed with status ${res.status}` };
+}
+
+export interface StartRunOptions {
+  /** A flow to run under dev semantics (mutually exclusive with `artifact`). */
+  flow?: WorkflowDefinition;
+  /** A sealed artifact to run under production semantics (mutually exclusive with `flow`). */
+  artifact?: PublishedArtifact;
+  /** Pinned node outputs; ignored/rejected by the runner in production. */
+  pins?: Record<string, unknown>;
+  /** The invocation payload, exposed to nodes as ctx.runInput. */
+  input?: Record<string, unknown>;
+  /** Explicit env override; artifact runs always force 'production' regardless. */
+  env?: 'dev' | 'production';
+  /** Named environment to run against (from emberflow.environments.json); omitted → runner default. */
+  environment?: string;
+  /** Explicit safe-mode override; omitted → environment's default (protected ⇒ true). */
+  safeMode?: boolean;
+  /** Required to equal `environment` when explicitly disabling safe mode on a protected environment. */
+  confirm?: string;
+}
+
+export async function startRun(opts: StartRunOptions): Promise<string> {
+  const { flow, artifact, pins, input, env, environment, safeMode, confirm } = opts;
+  const { runId } = await request<{ runId: string }>('/runs', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ flow, artifact, mode: 'run', pins, input, env, environment, safeMode, confirm }),
+  });
+  return runId;
+}
+
+export interface EnvironmentSummary {
+  name: string;
+  protected: boolean;
+  varKeys: string[];
+  secretKeys: string[];
+  auth?: { configured: boolean; authenticated: boolean; secretRef?: string };
+}
+
+export async function listEnvironments(): Promise<{ defaultEnvironment: string; environments: EnvironmentSummary[] }> {
+  return request('/environments');
+}
+
+/** Performs the named environment's configured login, storing the captured
+ *  credential runner-side. Never returns the secret value — only whether the
+ *  login succeeded and which secret it landed in. */
+export async function loginEnvironment(name: string): Promise<{ authenticated: boolean; secretRef: string }> {
+  return request(`/environments/${encodeURIComponent(name)}/login`, { method: 'POST' });
+}
+
+/** Sets (or, when `auth` is `null`, clears) an environment's auth config via
+ *  `PUT /environments/:name/auth`. Never sends secret values — `auth` carries
+ *  only refs/names (attach.secretRef, login.request.bodyRef). 204 on success. */
+export async function setEnvironmentAuth(name: string, auth: unknown): Promise<void> {
+  await request(`/environments/${encodeURIComponent(name)}/auth`, {
+    method: 'PUT',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(auth),
+  });
+}
+
+/** Flips whether mounted HTTP endpoints execute for real or answer from
+ *  scenario expectations (mock), via `POST /serving`. 204 on success; a
+ *  bogus mode is rejected by the runner (surfaced via request()'s error path). */
+export async function setServingMode(mode: 'real' | 'mock'): Promise<void> {
+  await request('/serving', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ mode }),
+  });
+}
+
+export async function samples(nodeId: string): Promise<NodeExecutionSample[]> {
+  const { samples: results } = await request<{ samples: NodeExecutionSample[] }>(
+    `/samples?nodeId=${encodeURIComponent(nodeId)}`,
+  );
+  return results;
+}
+
+/**
+ * Opens the run's SSE stream and collects events until `finished`.
+ * Parses the stream by hand: messages are separated by a blank line, each
+ * made of `event:`/`data:` lines; lines starting with `:` are heartbeat
+ * comments and are ignored.
+ */
+export async function waitForRun(runId: string): Promise<{ run: WorkflowRun; logs: LogLine[] }> {
+  let res: Response;
+  try {
+    res = await fetch(`${baseUrl()}/runs/${encodeURIComponent(runId)}/events`);
+  } catch (err) {
+    throw new RunnerUnreachableError(err);
+  }
+  if (!res.ok || !res.body) {
+    throw new Error(`Failed to open event stream for run ${runId}: ${res.status} ${res.statusText}`);
+  }
+
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+  const logs: LogLine[] = [];
+  let finalRun: WorkflowRun | undefined;
+
+  const processMessage = (raw: string): void => {
+    const dataLines: string[] = [];
+    for (const line of raw.split('\n')) {
+      if (line.length === 0 || line.startsWith(':')) continue;
+      if (line.startsWith('data:')) dataLines.push(line.slice(5).trimStart());
+    }
+    if (dataLines.length === 0) return;
+    const event = JSON.parse(dataLines.join('\n')) as RunEvent;
+    if (event.type === 'log') logs.push(event.line);
+    else if (event.type === 'finished') finalRun = event.run;
+  };
+
+  try {
+    while (!finalRun) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      let sepIndex: number;
+      while ((sepIndex = buffer.indexOf('\n\n')) !== -1) {
+        const raw = buffer.slice(0, sepIndex);
+        buffer = buffer.slice(sepIndex + 2);
+        processMessage(raw);
+        if (finalRun) break;
+      }
+    }
+  } finally {
+    reader.cancel().catch(() => {});
+  }
+
+  if (!finalRun) throw new Error(`Run ${runId} stream ended before a "finished" event was received`);
+  return { run: finalRun, logs };
+}

package/server/demoProject.test.ts

@@ -0,0 +1,29 @@
+// server/demoProject.test.ts
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { loadProjectConfig } from './projectConfig';
+import { buildFlowStore, buildRegistries } from './projectMode';
+import { startRun } from '../src/engine';
+
+const FIXTURE = resolve(__dirname, '../examples/demo-project');
+
+describe('demo project (committed fixture)', () => {
+  it('loads, registers TriageOrder, and every scenario runs green', async () => {
+    const project = await loadProjectConfig(FIXTURE);
+    expect(project).not.toBeNull();
+    const store = buildFlowStore(project);
+    const flow = store.load('order-triage')!;
+    expect(flow.scenarios).toHaveLength(3);
+    const { execution } = buildRegistries(project);
+    const expected: Record<string, { tier: string; rush: boolean }> = {
+      'standard-order': { tier: 'standard', rush: false },
+      'priority-rush': { tier: 'priority', rush: true },
+      vip: { tier: 'vip', rush: false },
+    };
+    for (const sc of flow.scenarios!) {
+      const run = await startRun({ flow, registry: execution, input: sc.input }).runToEnd();
+      expect(run.status).toBe('succeeded');
+      expect(run.nodeStates.triage.output).toEqual(expected[sc.name]);
+    }
+  });
+});

package/server/diagnosticsRoute.test.ts

@@ -0,0 +1,169 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { spawn, type ChildProcess } from 'node:child_process';
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+// Verifies GET /workflows/:id/diagnostics (Task 2) plus normalize-on-write
+// (seedParamDefaults called from PUT /workflows/:id and POST /operations
+// before persisting). Boots the real runner subprocess against a scratch
+// project dir, mirroring server/workflowTestRoute.test.ts's harness.
+
+let proc: ChildProcess;
+const PORT = 8146;
+const base = `http://127.0.0.1:${PORT}`;
+let projectDir: string;
+let apisDir: 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',
+  });
+}
+
+function noParamOp(id: string) {
+  return {
+    id,
+    name: id,
+    version: 1,
+    http: { method: 'GET', path: `/${id}` },
+    nodes: [
+      {
+        id: 'input',
+        type: 'Input',
+        label: 'Input',
+        position: { x: 0, y: 0 },
+        config: { fields: [] },
+      },
+      {
+        id: 'response',
+        type: 'Response',
+        label: 'Response',
+        position: { x: 200, y: 0 },
+        config: { status: 200, body: { ok: true } },
+      },
+    ],
+    edges: [{ id: 'e1', source: 'input', target: 'response' }],
+    createdAt: '2026-01-01T00:00:00Z',
+    updatedAt: '2026-01-01T00:00:00Z',
+  };
+}
+
+function withParamNoDefault(id: string) {
+  const op = noParamOp(id);
+  op.http = { method: 'GET', path: `/${id}/:id` };
+  return op;
+}
+
+beforeAll(async () => {
+  projectDir = mkdtempSync(join(tmpdir(), 'diagnosticsroute-'));
+  writeFileSync(join(projectDir, 'emberflow.config.mjs'), 'export default {};\n');
+  apisDir = join(projectDir, 'emberflow', 'apis', 'default');
+  mkdirSync(apisDir, { recursive: true });
+
+  writeFileSync(join(apisDir, 'needs-default.json'), JSON.stringify(withParamNoDefault('needs-default')));
+
+  proc = bootRunner(PORT, { EMBERFLOW_PROJECT: projectDir });
+  await waitHealthy(`${base}/healthz`);
+}, 20_000);
+
+afterAll(async () => {
+  proc?.kill();
+  if (projectDir) rmSync(projectDir, { recursive: true, force: true });
+});
+
+describe('GET /workflows/:id/diagnostics', () => {
+  it('includes missing-param-default for a path param with no default', async () => {
+    const res = await fetch(`${base}/api/workflows/needs-default/diagnostics`);
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    const codes = body.diagnostics.map((d: { code: string }) => d.code);
+    expect(codes).toContain('missing-param-default');
+    const diag = body.diagnostics.find((d: { code: string }) => d.code === 'missing-param-default');
+    expect(diag.severity).toBe('warning');
+    expect(diag.param).toBe('id');
+  });
+
+  it('404s for an unknown op id', async () => {
+    const res = await fetch(`${base}/api/workflows/no-such-op/diagnostics`);
+    expect(res.status).toBe(404);
+    const body = await res.json();
+    expect(body.error).toBeTruthy();
+  });
+});
+
+describe('normalize-on-write: PUT /workflows/:id', () => {
+  it('seeds an empty-string default for a path param missing one, and persists it to disk', async () => {
+    const flow = withParamNoDefault('default/put-seed-test');
+    const createRes = await fetch(`${base}/api/operations`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ flow, path: 'default/put-seed-test' }),
+    });
+    expect(createRes.status).toBe(201);
+
+    const putRes = await fetch(`${base}/api/workflows/${encodeURIComponent('default/put-seed-test')}`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(flow),
+    });
+    expect(putRes.status).toBe(200);
+
+    const onDisk = JSON.parse(readFileSync(join(apisDir, 'put-seed-test.json'), 'utf8'));
+    expect(onDisk.nodes.find((n: { type: string }) => n.type === 'Input').config.defaults.params.id).toBe('');
+  });
+
+  it('preserves an existing real default value on PUT — never overwrites', async () => {
+    const flow = withParamNoDefault('default/put-preserve-test');
+    (flow.nodes[0] as { config: Record<string, unknown> }).config = {
+      fields: [],
+      defaults: { params: { id: 'real-id-value' } },
+    };
+    const createRes = await fetch(`${base}/api/operations`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ flow, path: 'default/put-preserve-test' }),
+    });
+    expect(createRes.status).toBe(201);
+
+    const putRes = await fetch(`${base}/api/workflows/${encodeURIComponent('default/put-preserve-test')}`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(flow),
+    });
+    expect(putRes.status).toBe(200);
+
+    const onDisk = JSON.parse(readFileSync(join(apisDir, 'put-preserve-test.json'), 'utf8'));
+    expect(onDisk.nodes.find((n: { type: string }) => n.type === 'Input').config.defaults.params.id).toBe(
+      'real-id-value',
+    );
+  });
+});
+
+describe('normalize-on-write: POST /operations', () => {
+  it('seeds an empty-string default for a path param missing one, and persists it to disk', async () => {
+    const flow = withParamNoDefault('default/post-seed-test');
+    const res = await fetch(`${base}/api/operations`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ flow, path: 'default/post-seed-test' }),
+    });
+    expect(res.status).toBe(201);
+
+    const onDisk = JSON.parse(readFileSync(join(apisDir, 'post-seed-test.json'), 'utf8'));
+    expect(onDisk.nodes.find((n: { type: string }) => n.type === 'Input').config.defaults.params.id).toBe('');
+  });
+});