@xdelivered/emberflow 0.2.0

package/server/openBrowser.ts

@@ -0,0 +1,22 @@
+import { spawn as nodeSpawn } from 'node:child_process';
+
+interface OpenDeps {
+  platform?: NodeJS.Platform;
+  spawn?: typeof nodeSpawn;
+}
+
+/** Open the default browser at `url`. Best-effort — never throws into the caller. */
+export function openBrowser(url: string, deps: OpenDeps = {}): void {
+  const platform = deps.platform ?? process.platform;
+  const spawn = deps.spawn ?? nodeSpawn;
+  const [cmd, args] =
+    platform === 'darwin' ? ['open', [url]]
+    : platform === 'win32' ? ['cmd', ['/c', 'start', '', url]]
+    : ['xdg-open', [url]];
+  try {
+    const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+    child.unref?.();
+  } catch {
+    // headless / no browser — the URL is printed by the caller anyway
+  }
+}

package/server/operationResult.test.ts

@@ -0,0 +1,67 @@
+import { expect, it } from 'vitest';
+import { extractResponse } from './operationResult';
+import type { WorkflowDefinition } from '../src/engine';
+
+const base = { version: 1, createdAt: '2026-01-01T00:00:00Z', updatedAt: '2026-01-01T00:00:00Z' };
+
+it('returns the Response node output when present', () => {
+  const flow = { ...base, id: 'f', name: 'F', edges: [],
+    nodes: [{ id: 'r', type: 'Response', label: 'R', position: { x: 0, y: 0 }, config: {} }] } as unknown as WorkflowDefinition;
+  const run = { nodeStates: { r: { status: 'succeeded', output: { status: 204, body: null } } } } as never;
+  expect(extractResponse(run, flow)).toEqual({ status: 204, body: null });
+});
+
+it('picks the Response node that actually succeeded, not the first by array order', () => {
+  // Two Response nodes: 'first' is earlier in the array but was skipped
+  // (nodeStates status !== 'succeeded', output undefined); 'second' ran and
+  // succeeded. The real result is the second node's output, not a fallback
+  // to 200 + Result.
+  const flow = {
+    ...base,
+    id: 'f',
+    name: 'F',
+    edges: [],
+    nodes: [
+      { id: 'first', type: 'Response', label: 'First', position: { x: 0, y: 0 }, config: {} },
+      { id: 'second', type: 'Response', label: 'Second', position: { x: 0, y: 0 }, config: {} },
+    ],
+  } as unknown as WorkflowDefinition;
+  const run = {
+    nodeStates: {
+      first: { status: 'skipped', output: undefined },
+      second: { status: 'succeeded', output: { status: 404, body: { error: 'nf' } } },
+    },
+  } as never;
+  expect(extractResponse(run, flow)).toEqual({ status: 404, body: { error: 'nf' } });
+});
+
+it('defaults to 200 + Result output when there is no Response node', () => {
+  const flow = { ...base, id: 'f', name: 'F', edges: [],
+    nodes: [{ id: 'res', type: 'Result', label: 'Res', position: { x: 0, y: 0 }, config: {} }] } as unknown as WorkflowDefinition;
+  const run = { status: 'succeeded', nodeStates: { res: { status: 'succeeded', output: { hello: 'world' } } } } as never;
+  expect(extractResponse(run, flow)).toEqual({ status: 200, body: { hello: 'world' } });
+});
+
+it('returns 500 with the failing node error when the run failed and there is no Response node', () => {
+  const flow = { ...base, id: 'f', name: 'F', edges: [],
+    nodes: [{ id: 'n', type: 'HttpRequest', label: 'N', position: { x: 0, y: 0 }, config: {} }] } as unknown as WorkflowDefinition;
+  const run = { status: 'failed', nodeStates: { n: { status: 'failed', error: 'boom: connection refused' } } } as never;
+  expect(extractResponse(run, flow)).toEqual({
+    status: 500,
+    body: { error: 'run failed', detail: 'boom: connection refused' },
+  });
+});
+
+it('returns 500 with a generic body when the run failed but no node error is available', () => {
+  const flow = { ...base, id: 'f', name: 'F', edges: [],
+    nodes: [{ id: 'n', type: 'HttpRequest', label: 'N', position: { x: 0, y: 0 }, config: {} }] } as unknown as WorkflowDefinition;
+  const run = { status: 'failed', nodeStates: { n: { status: 'failed' } } } as never;
+  expect(extractResponse(run, flow)).toEqual({ status: 500, body: { error: 'run failed' } });
+});
+
+it('a succeeded Response node still wins even if the overall run status looks failed', () => {
+  const flow = { ...base, id: 'f', name: 'F', edges: [],
+    nodes: [{ id: 'r', type: 'Response', label: 'R', position: { x: 0, y: 0 }, config: {} }] } as unknown as WorkflowDefinition;
+  const run = { status: 'failed', nodeStates: { r: { status: 'succeeded', output: { status: 201, body: { ok: true } } } } } as never;
+  expect(extractResponse(run, flow)).toEqual({ status: 201, body: { ok: true } });
+});

package/server/operationResult.ts

@@ -0,0 +1,27 @@
+import { runOutput, type WorkflowDefinition, type WorkflowRun } from '../src/engine';
+
+/** Map a finished operation run to an HTTP response. A flow can have more than
+ *  one `Response` node (e.g. a success branch and an error branch) — only one
+ *  of them actually ran. Among the `Response`-type nodes, pick the one whose
+ *  run state actually succeeded (first such node by array order if somehow
+ *  more than one did); its output (already `{ status, body }`) wins.
+ *  Otherwise — no Response node, or none of them succeeded — fall back to
+ *  200 + the run's Result output. */
+export function extractResponse(run: WorkflowRun, flow: WorkflowDefinition): { status: number; body: unknown } {
+  const responseNodes = flow.nodes.filter((n) => n.type === 'Response');
+  const succeeded = responseNodes.find((n) => run.nodeStates[n.id]?.status === 'succeeded');
+  const out = succeeded ? run.nodeStates[succeeded.id]?.output : undefined;
+  if (out && typeof out === 'object') {
+    const o = out as { status?: unknown; body?: unknown };
+    return { status: typeof o.status === 'number' ? o.status : 200, body: o.body };
+  }
+  // No Response node succeeded. If the run itself failed, a 200 fallback would
+  // silently mask the failure (runOutput returns undefined → 200 + null). Surface
+  // it as a 500, preferring the first failed node's error string (a stable shape,
+  // no stack traces) so the caller sees why.
+  if (run.status === 'failed') {
+    const nodeError = Object.values(run.nodeStates).find((s) => s?.status === 'failed')?.error;
+    return { status: 500, body: nodeError ? { error: 'run failed', detail: nodeError } : { error: 'run failed' } };
+  }
+  return { status: 200, body: runOutput(run, flow) };
+}

package/server/pathGuard.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest';
+import { isMountablePath } from './pathGuard';
+
+describe('isMountablePath', () => {
+  it('rejects bare root, empty, missing, no-leading-slash, and double-slash paths', () => {
+    expect(isMountablePath('/')).toBe(false);
+    expect(isMountablePath('')).toBe(false);
+    expect(isMountablePath(undefined)).toBe(false);
+    expect(isMountablePath(null)).toBe(false);
+    expect(isMountablePath('no-leading-slash')).toBe(false);
+    expect(isMountablePath('//x')).toBe(false);
+  });
+
+  it('accepts real sub-paths', () => {
+    expect(isMountablePath('/things')).toBe(true);
+    expect(isMountablePath('/a/b')).toBe(true);
+    expect(isMountablePath('/things/:id')).toBe(true);
+  });
+});

package/server/pathGuard.ts

@@ -0,0 +1,12 @@
+// A mountable operation `http.path` must be a real sub-path — never bare
+// root ('/' or '') and never missing. Operation routes are registered
+// before the studio SPA catch-all, so an op mounted at '/' would shadow the
+// studio entirely (GET / would return the op's output, not the studio
+// HTML). Roughly `^/[^/].*`.
+export function isMountablePath(path: string | undefined | null): path is string {
+  if (!path) return false;
+  if (path.length < 2) return false; // '/' or ''
+  if (path[0] !== '/') return false;
+  if (path[1] === '/') return false; // '//x'
+  return true;
+}

package/server/pathSafety.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest';
+import { isPathWithin } from './pathSafety';
+
+describe('isPathWithin', () => {
+  const base = '/project/apis';
+
+  it('allows simple nested relative paths', () => {
+    expect(isPathWithin(base, 'svc/thing')).toBe(true);
+    expect(isPathWithin(base, 'a/b/c')).toBe(true);
+    expect(isPathWithin(base, 'billing/charge')).toBe(true);
+  });
+
+  it('rejects parent traversal', () => {
+    expect(isPathWithin(base, '../x')).toBe(false);
+    expect(isPathWithin(base, 'a/../../b')).toBe(false);
+    expect(isPathWithin(base, 'a/../b')).toBe(false);
+  });
+
+  it('rejects absolute paths', () => {
+    expect(isPathWithin(base, '/etc/x')).toBe(false);
+  });
+
+  it('rejects empty strings and empty segments', () => {
+    expect(isPathWithin(base, '')).toBe(false);
+    expect(isPathWithin(base, 'a//b')).toBe(false);
+  });
+
+  it('rejects backslash segments (Windows separator smuggling a traversal)', () => {
+    expect(isPathWithin(base, 'a\\..\\b')).toBe(false);
+    expect(isPathWithin(base, 'a\\b')).toBe(false);
+  });
+
+  it('rejects a bare "." or ".." segment', () => {
+    expect(isPathWithin(base, '.')).toBe(false);
+    expect(isPathWithin(base, '..')).toBe(false);
+    expect(isPathWithin(base, 'a/.')).toBe(false);
+  });
+});

package/server/pathSafety.ts

@@ -0,0 +1,33 @@
+import { isAbsolute, relative, resolve } from 'node:path';
+
+/**
+ * True when `relPath` is a safe POSIX-style relative path that, once joined
+ * onto `baseDir`, resolves to somewhere *inside* `baseDir`.
+ *
+ * Rejects:
+ *  - empty strings
+ *  - a leading `/` (absolute)
+ *  - a backslash anywhere (the Windows separator — letting it through would
+ *    let a segment like `a\..\b` smuggle a traversal past the POSIX-only
+ *    `'/'.split` checks below, and still resolve outside `baseDir` via
+ *    `path.join`'s platform-specific behavior)
+ *  - any `.`/`..`/empty segment (so `a//b`, `./x`, `../x` are all rejected)
+ *  - anything that, after resolution, doesn't stay under `baseDir` (defense
+ *    in depth beyond the segment checks above)
+ *
+ * Shared by `isSafeApiPath` (server/index.ts, POST /operations and future
+ * path-taking endpoints) and `isSafeFlowId` (server/agents/runManager.ts) —
+ * one robust implementation instead of two ad hoc string checks.
+ */
+export function isPathWithin(baseDir: string, relPath: string): boolean {
+  if (typeof relPath !== 'string' || relPath.length === 0) return false;
+  if (relPath.includes('\\')) return false;
+  if (relPath.startsWith('/')) return false;
+  const segments = relPath.split('/');
+  if (segments.some((seg) => seg === '' || seg === '.' || seg === '..')) return false;
+
+  const resolvedBase = resolve(baseDir);
+  const resolved = resolve(baseDir, relPath);
+  const rel = relative(resolvedBase, resolved);
+  return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
+}

package/server/projectConfig.test.ts

@@ -0,0 +1,67 @@
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { loadProjectConfig } from './projectConfig';
+
+const dirs: string[] = [];
+function scratch(): string {
+  const d = mkdtempSync(join(tmpdir(), 'ef-proj-'));
+  dirs.push(d);
+  return d;
+}
+afterEach(() => { for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true }); });
+
+describe('loadProjectConfig', () => {
+  it('returns null when no config file exists', async () => {
+    expect(await loadProjectConfig(scratch())).toBeNull();
+  });
+
+  it('loads emberflow.config.mjs, resolving flowsDir against the config dir', async () => {
+    const d = scratch();
+    mkdirSync(join(d, 'my-flows'));
+    writeFileSync(
+      join(d, 'emberflow.config.mjs'),
+      `export default { flowsDir: 'my-flows', registerNodes: (r) => { r.register({ type: 'X', label: 'X' }, async () => ({})); } };\n`,
+    );
+    const cfg = await loadProjectConfig(d);
+    expect(cfg).not.toBeNull();
+    expect(cfg!.root).toBe(d);
+    expect(cfg!.flowsDir).toBe(join(d, 'my-flows'));
+    expect(typeof cfg!.registerNodes).toBe('function');
+  });
+
+  it('defaults flowsDir to <root>/emberflow/flows and creates nothing', async () => {
+    const d = scratch();
+    writeFileSync(join(d, 'emberflow.config.mjs'), `export default {};\n`);
+    const cfg = await loadProjectConfig(d);
+    expect(cfg!.flowsDir).toBe(join(d, 'emberflow', 'flows'));
+  });
+
+  it('throws a readable error for an unparseable config', async () => {
+    const d = scratch();
+    writeFileSync(join(d, 'emberflow.config.mjs'), `export default {;\n`);
+    await expect(loadProjectConfig(d)).rejects.toThrow(/emberflow\.config/);
+  });
+
+  it('infers language "javascript" from a .mjs config when unset', async () => {
+    const d = scratch();
+    writeFileSync(join(d, 'emberflow.config.mjs'), `export default {};\n`);
+    const cfg = await loadProjectConfig(d);
+    expect(cfg!.language).toBe('javascript');
+  });
+
+  it('infers language "typescript" from a .ts config when unset', async () => {
+    const d = scratch();
+    writeFileSync(join(d, 'emberflow.config.ts'), `export default {};\n`);
+    const cfg = await loadProjectConfig(d);
+    expect(cfg!.language).toBe('typescript');
+  });
+
+  it('explicit language field wins over extension inference', async () => {
+    const d = scratch();
+    writeFileSync(join(d, 'emberflow.config.mjs'), `export default { language: 'typescript' };\n`);
+    const cfg = await loadProjectConfig(d);
+    expect(cfg!.language).toBe('typescript');
+  });
+});

package/server/projectConfig.ts

@@ -0,0 +1,101 @@
+import { existsSync } from 'node:fs';
+import { extname, isAbsolute, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import type { NodeRegistry } from '../src/engine';
+import type { VerifierRegistry } from './auth/verifiers';
+
+/**
+ * Project mode: a consumer repo drops an emberflow.config file at its root
+ * and Emberflow serves THEIR flows and nodes. This loader finds and imports
+ * that config. The runner runs under tsx, so dynamic import handles .ts
+ * configs as well as .js/.mjs.
+ */
+
+const CONFIG_BASENAMES = ['emberflow.config.mjs', 'emberflow.config.js', 'emberflow.config.ts'];
+
+export interface EmberflowUserConfig {
+  /** Directory holding <flowId>.json flow files (+ <flowId>.scenarios.json sidecars). Relative to the config file. */
+  flowsDir?: string;
+  /** Register the project's own node types. */
+  registerNodes?: (registry: NodeRegistry) => void;
+  /** Register custom auth verifiers (e.g. real JWT) alongside the default bearer/apiKey ones. */
+  registerVerifiers?: (registry: VerifierRegistry) => void;
+  /** Op id to run when any run finishes with status 'failed' (best-effort; never blocks the failed run). */
+  errorOperation?: string;
+  /** Authoritative signal for agents/tooling about which language this project's
+   *  APIs/nodes are authored in. When absent, it's inferred from the config file's
+   *  own extension (`emberflow.config.ts` → 'typescript', else 'javascript'). */
+  language?: 'javascript' | 'typescript';
+}
+
+/** Identity helper so consumer configs get typing: `export default defineConfig({...})`. */
+export function defineConfig(config: EmberflowUserConfig): EmberflowUserConfig {
+  return config;
+}
+
+export interface ProjectConfig {
+  root: string;
+  flowsDir: string;
+  language: 'javascript' | 'typescript';
+  /** Present only when the config's `language` field was EXPLICIT and
+   *  disagrees with the config file's own extension (e.g. `language:
+   *  'javascript'` in an `emberflow.config.ts`). Inference makes language and
+   *  extension agree by construction, so this is the only detectable drift —
+   *  see src/engine/diagnostics.ts's `language-drift` check, which callers
+   *  (server/index.ts's diagnostics route, `doctor`) feed this into. */
+  languageDrift?: { projectLanguage: 'javascript' | 'typescript'; configPathExtension: string };
+  registerNodes?: (registry: NodeRegistry) => void;
+  registerVerifiers?: (registry: VerifierRegistry) => void;
+  errorOperation?: string;
+}
+
+/** The resolved emberflow.config.* path for a project dir, or undefined. */
+export function configPathFor(dir: string): string | undefined {
+  const root = resolve(dir);
+  return CONFIG_BASENAMES.map((b) => join(root, b)).find(existsSync);
+}
+
+/**
+ * Loads a project's config. `fresh: true` cache-busts the dynamic import so an
+ * edited config re-imports (the module loader caches by URL) — used by the
+ * in-process node hot-reload so editing registerNodes takes effect without a
+ * process restart (which would kill in-flight agent runs).
+ */
+export async function loadProjectConfig(
+  dir: string,
+  opts: { fresh?: boolean } = {},
+): Promise<ProjectConfig | null> {
+  const root = resolve(dir);
+  const file = CONFIG_BASENAMES.map((b) => join(root, b)).find(existsSync);
+  if (!file) return null;
+  let raw: EmberflowUserConfig;
+  try {
+    const url = pathToFileURL(file).href + (opts.fresh ? `?t=${Date.now()}` : '');
+    const mod = (await import(url)) as { default?: EmberflowUserConfig };
+    raw = mod.default ?? {};
+  } catch (err) {
+    throw new Error(`Failed to load ${file}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  const flowsDir = raw.flowsDir
+    ? isAbsolute(raw.flowsDir) ? raw.flowsDir : join(root, raw.flowsDir)
+    : join(root, 'emberflow', 'flows');
+  // Explicit `language` wins; otherwise infer from the config file's own
+  // extension — a .ts config implies a TypeScript project, everything else JS.
+  const inferredLanguage: 'javascript' | 'typescript' = file.endsWith('.ts') ? 'typescript' : 'javascript';
+  const language: 'javascript' | 'typescript' = raw.language ?? inferredLanguage;
+  // Drift is only detectable when the field is EXPLICIT: inferred language
+  // agrees with the extension by construction, so there's nothing to flag.
+  const languageDrift =
+    raw.language && raw.language !== inferredLanguage
+      ? { projectLanguage: raw.language, configPathExtension: extname(file) }
+      : undefined;
+  return {
+    root,
+    flowsDir,
+    language,
+    ...(languageDrift ? { languageDrift } : {}),
+    ...(raw.registerNodes ? { registerNodes: raw.registerNodes } : {}),
+    ...(raw.registerVerifiers ? { registerVerifiers: raw.registerVerifiers } : {}),
+    ...(raw.errorOperation ? { errorOperation: raw.errorOperation } : {}),
+  };
+}

package/server/projectMode.test.ts

@@ -0,0 +1,106 @@
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { loadProjectConfig } from './projectConfig';
+import { buildRegistries, buildFlowStore, buildApiStore, requireProjectWhenExplicit } from './projectMode';
+import { startRun } from '../src/engine';
+
+const dirs: string[] = [];
+function scratch(): string {
+  const d = mkdtempSync(join(tmpdir(), 'ef-mode-'));
+  dirs.push(d);
+  return d;
+}
+afterEach(() => { for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true }); });
+
+function writeFixture(d: string): void {
+  mkdirSync(join(d, 'flows'), { recursive: true });
+  writeFileSync(join(d, 'emberflow.config.mjs'), `export default {
+  flowsDir: 'flows',
+  registerNodes(registry) {
+    registry.register(
+      { type: 'Shout', label: 'Shout', inputSchema: { fields: [{ name: 'text', type: 'string', required: true }] } },
+      async (ctx) => ({ loud: String(ctx.input.text).toUpperCase() + '!' }),
+    );
+  },
+};\n`);
+  writeFileSync(join(d, 'flows', 'hello.json'), JSON.stringify({
+    id: 'hello', name: 'Hello', version: 1,
+    nodes: [
+      { id: 'in', type: 'Input', label: 'In', position: { x: 0, y: 0 }, config: { fields: [{ name: 'text', type: 'string', required: true }] } },
+      { id: 'shout', type: 'Shout', label: 'Shout', position: { x: 200, y: 0 }, config: {}, inputMap: { text: { sourceNodeId: 'in', sourceField: 'text' } } },
+    ],
+    edges: [{ id: 'e1', source: 'in', target: 'shout' }],
+    createdAt: '2026-01-01T00:00:00Z', updatedAt: '2026-01-01T00:00:00Z',
+  }, null, 2));
+  writeFileSync(join(d, 'flows', 'hello.scenarios.json'), JSON.stringify([
+    { id: 's1', name: 'greet', input: { text: 'hi' } },
+  ]));
+}
+
+describe('project mode wiring', () => {
+  it('serves project flows with sidecar scenarios and runs consumer nodes', async () => {
+    const d = scratch();
+    writeFixture(d);
+    const project = await loadProjectConfig(d);
+    expect(project).not.toBeNull();
+    const store = buildFlowStore(project);
+    const flow = store.load('hello')!;
+    expect(flow.scenarios?.[0].name).toBe('greet');
+    const { execution } = buildRegistries(project);
+    const run = await startRun({ flow, registry: execution, input: flow.scenarios![0].input }).runToEnd();
+    expect(run.status).toBe('succeeded');
+    expect(run.nodeStates.shout.output).toEqual({ loud: 'HI!' });
+  });
+
+  it('buildApiStore migrates a project with a custom-named flowsDir (not literally "flows")', async () => {
+    const d = scratch();
+    mkdirSync(join(d, 'my-flows'), { recursive: true });
+    writeFileSync(
+      join(d, 'my-flows', 'onboarding.json'),
+      JSON.stringify({ id: 'onboarding', name: 'Onboarding', nodes: [], edges: [] }, null, 2),
+    );
+    writeFileSync(
+      join(d, 'emberflow.config.mjs'),
+      `export default { flowsDir: 'my-flows', registerNodes: () => {} };\n`,
+    );
+    const project = await loadProjectConfig(d);
+    expect(project).not.toBeNull();
+
+    const apiStore = buildApiStore(project);
+
+    // migration ran: apis/default now holds the flow, my-flows/ is gone.
+    expect(existsSync(join(d, 'apis', 'default', 'onboarding.json'))).toBe(true);
+    expect(existsSync(join(d, 'my-flows'))).toBe(false);
+    const tree = apiStore.tree();
+    const ids = tree.apis.flatMap((a) => a.operations.map((op) => op.id));
+    expect(ids).toContain('onboarding');
+  });
+
+  it('null project falls back to default store dir and default registry', () => {
+    const store = buildFlowStore(null);
+    expect(store.dir.endsWith('workflows')).toBe(true);
+    const { validation, execution } = buildRegistries(null);
+    expect(validation.has('Input')).toBe(true);
+    expect(execution.has('Input')).toBe(true);
+    expect(execution.has('Shout')).toBe(false);
+  });
+});
+
+describe('requireProjectWhenExplicit', () => {
+  it('throws when EMBERFLOW_PROJECT is explicit but no config was found', () => {
+    expect(() => requireProjectWhenExplicit(null, '/tmp/typo-path', '/tmp/typo-path')).toThrow(
+      '/tmp/typo-path',
+    );
+  });
+
+  it('passes the project through when explicit and found', () => {
+    const project = { root: '/tmp/proj' } as never;
+    expect(requireProjectWhenExplicit(project, '/tmp/proj', '/tmp/proj')).toBe(project);
+  });
+
+  it('stays lenient when implicit (undefined) and no config was found', () => {
+    expect(requireProjectWhenExplicit(null, undefined, process.cwd())).toBeNull();
+  });
+});

package/server/projectMode.ts

@@ -0,0 +1,59 @@
+import { dirname, join, resolve } from 'node:path';
+import { FlowStore } from './flowStore';
+import { ApiStore } from './apiStore';
+import { migrateFlowsToApis } from './migrateFlows';
+import { createDefaultRegistry } from '../src/nodes';
+import type { NodeRegistry } from '../src/engine';
+import type { ProjectConfig } from './projectConfig';
+
+/**
+ * Project-mode wiring, kept Express-free so tests exercise exactly what the
+ * runner boots with. Two registries because validation and execution are
+ * separate instances in the runner — the consumer's nodes must exist in both.
+ */
+/**
+ * Boot-time guard: an explicit EMBERFLOW_PROJECT env var must fail loudly
+ * when no config was found there, mirroring the environments-file stance.
+ * Implicit cwd detection stays lenient (silent fallback to default mode).
+ */
+export function requireProjectWhenExplicit(
+  project: ProjectConfig | null,
+  explicitPath: string | undefined,
+  resolvedDir: string,
+): ProjectConfig | null {
+  if (explicitPath !== undefined && project === null) {
+    throw new Error(
+      `EMBERFLOW_PROJECT points at ${resolvedDir} but no emberflow.config.(mjs|js|ts) was found there`,
+    );
+  }
+  return project;
+}
+
+export function buildFlowStore(project: ProjectConfig | null): FlowStore {
+  return project ? new FlowStore(project.flowsDir, { scenarioSidecars: true }) : new FlowStore();
+}
+
+/**
+ * The `apis/` tree replaces the flat `flows/` layout. Runs the one-time
+ * migration before constructing the store so a legacy project boots straight
+ * into the new layout.
+ */
+export function buildApiStore(project: ProjectConfig | null): ApiStore {
+  const flowsDir = project ? project.flowsDir : resolve(process.cwd(), 'workflows', 'flows');
+  const apisDir = join(dirname(flowsDir), 'apis');
+  migrateFlowsToApis(flowsDir, apisDir);
+  return new ApiStore(apisDir);
+}
+
+export function buildRegistries(project: ProjectConfig | null): {
+  validation: NodeRegistry;
+  execution: NodeRegistry;
+} {
+  const validation = createDefaultRegistry();
+  const execution = createDefaultRegistry();
+  if (project?.registerNodes) {
+    project.registerNodes(validation);
+    project.registerNodes(execution);
+  }
+  return { validation, execution };
+}

package/server/redact.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from 'vitest';
+import { redactSecrets } from './redact';
+
+describe('redactSecrets', () => {
+  it('redacts a secret embedded inside a longer string', () => {
+    const payload = { line: 'cookie: session=SECRETVAL; Path=/' };
+    const result = redactSecrets(payload, { sessionCookie: 'SECRETVAL' });
+    expect(result).toEqual({ line: 'cookie: session=«secret:sessionCookie»; Path=/' });
+  });
+
+  it('redacts the URL-encoded form of a secret', () => {
+    const value = 'a b+c/d';
+    const encoded = encodeURIComponent(value);
+    const payload = { url: `https://x/y?token=${encoded}` };
+    const result = redactSecrets(payload, { apiToken: value });
+    expect(result).toEqual({ url: `https://x/y?token=«secret:apiToken»` });
+  });
+
+  it('redacts within nested objects and arrays', () => {
+    const payload = {
+      a: { b: ['prefix SECRETVAL suffix', { c: 'SECRETVAL again' }] },
+    };
+    const result = redactSecrets(payload, { key: 'SECRETVAL' });
+    expect(result).toEqual({
+      a: { b: ['prefix «secret:key» suffix', { c: '«secret:key» again' }] },
+    });
+  });
+
+  it('redacts multiple secrets in one payload', () => {
+    const payload = { line: 'user=USERSECRET pass=PASSSECRET' };
+    const result = redactSecrets(payload, { user: 'USERSECRET', pass: 'PASSSECRET' });
+    expect(result).toEqual({ line: 'user=«secret:user» pass=«secret:pass»' });
+  });
+
+  it('redacts multiple occurrences of one secret', () => {
+    const payload = { line: 'SECRETVAL and SECRETVAL again' };
+    const result = redactSecrets(payload, { key: 'SECRETVAL' });
+    expect(result).toEqual({ line: '«secret:key» and «secret:key» again' });
+  });
+
+  it('prefers the longer matching secret over one whose value is its substring', () => {
+    const payload = { line: 'value=XABCDEFY end' };
+    const result = redactSecrets(payload, { short: 'ABCDEF', long: 'XABCDEFY' });
+    expect(result).toEqual({ line: 'value=«secret:long» end' });
+  });
+
+  it('does not redact values shorter than 6 characters', () => {
+    const payload = { line: 'short=abcde end' };
+    const result = redactSecrets(payload, { short: 'abcde' });
+    expect(result).toEqual({ line: 'short=abcde end' });
+  });
+
+  it('leaves a payload with no strings unchanged', () => {
+    const payload = { n: 42, b: true, nil: null, list: [1, 2, 3] };
+    const result = redactSecrets(payload, { key: 'SECRETVAL' });
+    expect(result).toEqual(payload);
+  });
+
+  it('is the identity function when the secrets map is empty', () => {
+    const payload = { line: 'SECRETVAL stays', nested: { x: 'SECRETVAL' } };
+    const result = redactSecrets(payload, {});
+    expect(result).toEqual(payload);
+  });
+
+  it('does not mutate the input object', () => {
+    const payload = { line: 'SECRETVAL here', nested: { x: 'SECRETVAL' } };
+    const clone = JSON.parse(JSON.stringify(payload));
+    redactSecrets(payload, { key: 'SECRETVAL' });
+    expect(payload).toEqual(clone);
+  });
+
+  it('redacts the base64 form of a secret', () => {
+    const value = 'supersecret123';
+    const encoded = Buffer.from(value).toString('base64');
+    const payload = { line: `token=${encoded}` };
+    const result = redactSecrets(payload, { key: value });
+    expect(result).toEqual({ line: 'token=«secret:key»' });
+  });
+
+  it('redacts raw, url-encoded, and base64 forms of a secret in one payload', () => {
+    const value = 'a b+c/d';
+    const encoded = encodeURIComponent(value);
+    const b64 = Buffer.from(value).toString('base64');
+    const payload = { line: `raw=${value} enc=${encoded} b64=${b64}` };
+    const result = redactSecrets(payload, { key: value });
+    expect(result).toEqual({ line: 'raw=«secret:key» enc=«secret:key» b64=«secret:key»' });
+  });
+});